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PREFACE 


This manual describes the resident Operating System (OS) for the 
ATARI@ Home Computer, for readers who are familiar with the 
internal behavior of the system. It discusses: 


Q System functions and utilization techniques 

o Subsystem relationships and organization 

o Characteristics of the ATARI peripheral devices that can 
be attached to the ATARI400CTM] and ATARI SCOLTM] Home 
Computer 

o Advanced techniques for going beyond the basic OS 


capabilities 


oO The general features of the computer system hardware used 
by the OS. 


It would be helpful to have a familiarity with programming concepts 
and terminology. assembly language programming in general, the 
Synertek 6502 in particular, and digital hardware concepts and 
terminology. you will be provided with the information you need to 
use the 0S resources, without resorting to trial-and-error techniques 
or the OS listing. Supporting information for tasks that involve OS 
listing references is also provided. 


This manual does not present a comprehensive description of the 
hardware used to provide OS capabilites. The programmer who needs to 
go beyond the capabilities described should consult the ATARI Home 
Computer Hardware Manual. 
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1 INTRODUCTION 
GENERAL DESCRIPTION OF THE ATARI HOME COMPUTER SYSTEM 


Operating systems in the ATARI@ 400CTM] and ATARI SOOLTM] Home 
Computer are identical. The primary differences between the two are: 


a) Physical packaging 


o The ATARI 400 Computer console has one cartridge slot, the 
ATARI 80C Computer console has two cartridge slots 


o The ATARI 400 Home Computer contains 16K RAM and cannot be 
expanded. The ATARI 800 Home Computer can be expanded to a 
maximum of 48K RAM. 


o The ATARI 800 Computer has a monitor jacki the ATARI 400 
Computer does not. 


The Hardware Circuitry 


o Produces both character and point graphics for black and 
white (B/W) or color television. 


o Produces four independent audio channels (frequency 
controlled) which use the television sound system. 


o Provides one bi-level audio output in the base unit. 


o Interfaces with up to four Joysticks and eight Paddle 
Controllers. 


o Interfaces with a serial I/0 bus for expansion. 
o Contains a built-in keyboard 


Figure i-1i presents a simplified block diagram of the hardware. 
See the hardware manual for supporting documentation. 
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CONVENTIONS USED IN THIS MANUAL 
This manual uses the following special notations: 
Hexadecimal Numbers 


All two-digit numbers preceded by a dollar sign (%} designate 
hexadecimal numbers. All other numbers (except memory addresses) 


are in decimal form unless otherwise specified in the supporting 
text. 


Memory Addresses 


All references to computer memory and mapped I/0 locations are in 
hexadecimal notation. Memory addresses may or may not be contained 
in square brackets. (Example: (CD20F] and D2OF are the same 
address. ) 


Kilobytes of Memory 


Memory sizes are frequently expressed in units of kilobytes, such 
as 32K, where a kilobyte is 1024 bytes of memory. 


PASCAL As an Algorithm-Specification Language 


The PASCAL language (procedure block only) is used as the 
specification language in the few places where an algorithm is 
specified in detail. PASCAL syntax is similar to any number of 
other block-structured languages, and you should have no 
difficulty following the code presented. 


Memory Layouts 


Diagrams similar to Figure 1-2 are used whenever pictures of bytes 
or tables are presented: 


76$ 43210 
++ tt — 4-4-4 —- 4+ 


--~ This is a single byte. 
ph pe 


--~- This is a word (2 bytes). 


oe oe 


a ee eee ee eee ee eee cee 


=-~-~ This is a block of memory 
t of unspecified length. 


co oo a eo 


Sela alana dante dtaaia ates ene shoei cei 


Figure 1-2. Memory Layout Chart 
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Bit 7 is the most significant bit (MSB)} of the byte, and Bit O 
is the least significant bit (LSB). 


In tables and figures, memory addresses always increase toward the 
bottom of the figure. 


Backus-Naur Form 


A modified version of Backus-Naur Form (BNF) is used to express some 
syntactic forms, where the following metalinguistic symbols are used: 


[= is the substitution (assignment) operator. 
ee a metasyntactic variable. 


‘ separates alternative substitutions. 


ee an optional construct. 


Anything else is a syntactic literal constant, which stands for 
itself. 


For Example: 


<device specification> ::= <device name>ftdevice numbered: 
<device name> ::= CIDIEtKiPiRiS 


<device number> ::= 1L1:2:3'4itS5i6i7is8 


A “device specification” consists of a mandatory “device name, “ 
followed by an optional “device number." followed by the mandatory 
colon character. The device name in turn must be one of the 
characters shown as alternatives. The device number (if it is present? 


must be a digit 1 through 8. 


OS Equate Filenames 


Operating System ROM (Read Only Memory? and RAM (Random Access 
Memory) vector names, RAM database variable names and hardware 
register names are all referred to by the names assigned in the O5 
program equate list. When one of these names is used, the memory 
address is usually provided, such as BOOTAD [0242]. 
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2 OPERATING SYSTEM FUNCTIONAL ORGANIZATION 


This section describes the various subsystems of the resident OS in 
general terms. 


Input/Output Subsystem 


The Input/Output (1/0) subsystem provides a high-level interface 
between the programs and the hardware. Most functions are 
device-independent, such as the reading and writing of character data; 
yet provisions have been made for device-dependent functions as well. 
All peripheral devices capable of dealing with character data have 
individual symbolic names (such as K,D,P, etc). and can be accessed 
using a Central I/0 (CIO) routine. 


A RAM data base provides access to controllers (yoysticks and paddle 
controllers}, which do not deal with character data. This RAM data 
base 1s periodically updated to show the states of these devices. 


INTERRUPT PROCESSING 


The interrupt system handles all hardware interrupts in a common 
and consistent manner. By default, all interrupts are fielded by 
the 0S. At your discretion, individual interrupts (or 

groups of interrupts) can be fielded by the application program. 


INITIALIZATION 


The system provides two levels of initialization: power up and 
system reset. The OS performs power-up initialization each time 
the system power is switched to ON. and system reset 
initialization is performed each time the CSYSTEM. RESET] key is 
pressed. 


Power—Up 
The OS examines and notes the configuration of the unit whenever 


the system power is switched to ON. The system performs the following 
tasks at power up: 
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o Determines the highest RAM address. 


o Clears all of RAM to Zeros. 

o Establishes all RAM interrupt vectors. 
0 Formats the device table. 

o Initializes the cartridge(s}. 


QO Sets up the screen for 24 x 40 text mode. 


's) Boots the cassette if directed. 
o Checks cartridge slot(s) for diskette-boot instructions. 
0 Boots the diskette if directed to do so and a disk drive unit 


is attached. 


o Transfers control to the cartridge. diskette-booted program: 
cassette-booted program, or blackboard program. 


CSYSTEM. RESET] 


Pressing the CSYSTEM. RESET] key causes the 05 to perform these 
following tasks: 


o Clears the OS portion of RAM. 

Oo Rechecks top of RAM. 

0 Reestablishes all RAM interrupt vectors. 
o Formats the device table. 

o Initializes the cartridge(s). 

o Sets up the screen for 24 x 40 text mode. 


o Transfers control to the cartridge, a diskette-booted program, 
a cassette-booted program, or the blackboard program. 


Note that CSYSTEM. RESET] does not perform all the power-up 
tasks listed in the power-up section. 
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FLOATING POINT ARITHMETIC PACKAGE 


The OS ROM contains a Floating Point (FP} package that is available 
to nonresident programs such as ATARI BASIC. 


The package is not used by the other parts of the OS itself. 


The 


floating point numbers are stored as 10 BCD digits of mantissa, 
i-byte exponent. The package contains these routines: 


a4 


Q 


0 


ASCII-to-FP and FP-to-ASCII conversion. 
Integer-to-FP and FP-to-integer conversion. 
FP add. subtract, multiply and divide. 

FP log. exp, and polynomial evaluation. 


FP number clear, load, store. and move. 
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3 CONFIGURATIONS 


The ATARI 400 and ATARI 800 Home Computers support a 
wide variety of configurations, each with a unique operating 
environment: 


o Cartridge(s)} may or may not be inserted 


o Memory can be optionally added to the ATARI 800 Computer 
console in 16K increments 


o Many different peripheral devices can be attached to the 
serial [7/0 bus. 


The OS accounts for all of these variables without requiring a 
change in the resident OS itself (see Section 2). The machine 
configuration is checked when power is first turned on and then 
is not checked again, unless system reset is used. A general 
discussion of some of the valid configurations follows. 


PROGRAM ENVIRONMENTS 


The OS allows one of four program types to be in control at any 
point in time: 


o The OS blackboard (ATARI Memo Pad?) program 
o A cartridge-resident program 
o A diskette-booted program 
o A cassette-booted program 
Control choice is based upon information in the cartridge(s), upon 


whether or not a disk drive is attached, and upon operator keyboard 
inputs. The exact algorithms are discussed in detail in Section 7. 


Blackboard Mode 


In blackboard mode, the screen is established as a 24 x 40 text 
screen. Anything entered from the keyboard goes to the screen 
without being examined, although all of the screen editing 
functions are supported. Blackboard mode is the lowest priority 
environment. You go there only by command from a higher 
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priority environment. or by default, if there is no other 
reasonable environment for the OS to enter. For example, typing BYE 
in BASIC causes the OS to enter the blackboard mode. The blackboard 
mode can be exited by pressing the CSYSTEM. RESET] key if it was 
entered from a higher environment. 


Cartridge 


An inserted cartridge normally provides the main control after 
initialization is complete (for example: ATARI BASIC, SUPER 
BREAKOUTECTM], BASKETBALL, COMPUTER CHESS, and others. All these 
cartridge programs interface directly with you in some way). Although 
a cartridge can provide a supporting function for some other program 
environment. this has not yet been done. Some cartridges (particularly 
keyboard-oriented ones) can change environments by entering special 
commands (such as “BYE“) to go to blackboard mode or “DOS" to enter 
the disk utility. Other cartridges cannot change environments. Note 
that a hardware interlock prevents the removal or insertion of a 
cartridge with the power on; this feature causes the entire system to 
reinitialize with every cartridge change. 


Diskette Boot 


The diskette may or may not be booted when the system powers up 
with diskette-bootable software. This paragraph assumes that a 
diskette boot did occur. See Section 7 for boot condition 
explanations. 


The diskette-booted software can take control as the Disk Utility 
Program (DUP) does under certain conditions, or can provide a 
supporting function as the File Management System (FMS) does. This 
environment is so flexible that it is difficult to generalize on its 
capabilities and restrictions. The only machine requirement (other 
than the disk drive} is that sufficient RAM be installed to support 
the program being booted. 


Cassette-Boot 


The cassette-boot environment is similar to the diskette-boot 
environment, although the cassette is limited as an I/0 device. It 
is slow and can access only one file at a time in sequence. Note 
that the cassette-boot facility has no relation to the use of 
cassettes to store high-level language programs (e.g., programs 
written in ATARI BASIC). nor to the use of cassettes to store data. 
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RAM EXPANSION 


Although you can expand RAM noncontiguously in the 

ATARI 800 Home Computer, the OS will only recognize RAM 

that is contiguous starting from location 0. Installation 
directions are provided with the purchased RAM modules. RAM can be 
added until it totals 48K. After 32K, additional RAM overlays first 
the right-cartridge addresses (32K to 40K} and then the 
left-cartridge addresses (40K to 48K). Note that in cases of 
conflict, the inserted cartridge has higher priority and disables 
the conflicting RAM in 8K increments. See Section 4 for a detailed 
discussion of system memory. 


As a result of power-up, the OS will generate two pointers that 
define the lowest available RAM location and the highest available 
RAM location. The OS and diskette or cassette-booted software will 
determine the location of the lowest available RAM, while the 
number of RAM modules and the current screen mode will determine 
the highest available RAM. 


PERIPHERAL DEVICES 


Peripheral devices of several types can be added to the system 
using standard cables to either the serial bus or the connectors at 
the front of the computer console. The most common types deal with 
either transmission of bytes of data (usually serial bus? or 
transmission of sense information (usually game controllers}. 


Game Controllers 


The OS periodically senses (50 or 60 times per second) the standard 
game controllers (Paddles and Joysticks?) and the values read are 
stored in RAM. You can plug in. remove, and rearrange these 
controllers at will without affecting system operation, because the 
system will always try to read all of these controllers. 

The Driving Controllers are read, but not decoded, by the OS. Special 


instructions are required to read the keyboard controller (see 
Section ii>. 


Program Recorder 


The ATARI 410CTM] Program Recorder is a special peripheral. It uses 
the serial bus to send and receive data, but does not conform to 
the protocol of the other peripherals that use the serial bus. The 
Program Recorder must also be the last device on the serial bus, 
because it does not have a serial bus extender connector as the 
other peripherals do. There can never be more than one Program 
Recorder connected to any system for the same reason. The system 
cannot sense the presence or absence of the Program Recorder, so it 
can be connected and disconnected at will. 
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Serial Bus Bevices 


A serial bus device conforms to the serial I/O bus protocol as @ 
defined in Section 7 but this does not include the Program 

Recorder. Each serial bus device has two identical connectors: a 

serial bus input, and a serial bus extender. Either connector can 

be used for either purpose. Peripherals can be “daisychained" by 

cabling them together in a sequential fashion. There are usually no 
restrictions on the cabling order because each device has a unique 

identifier. Where restrictions exist, they will be mentioned in 

Section 5. 
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4 SYSTEM MEMORY UTILIZATION 


Memory in the system is decoded in the full S4K range of the 6502 
microcomputer and there are no provisions for additional mapping to 
extend memory. Memory is divided into four basic regions (with some 
overlap possible}: RAM, cartridge area, I/0 region and the resident 
OS ROM. The regions and their address boundaries are listed below 
(all addresses are in hexadecimal): 


OCOC-1FFF = RAM (minimum required for operation? 

2O00-7FFF = RAM expansion area ; 

BOO00-9FFF = Cartridge B. Cartridge A (half of 16K size) or RAM 
AOOCC-BFFF = Cartridge A or RAM S & 
COOG-CFFF = Unused iF 
DOOC-D7FF = Hardware I/O decodes UA 
DSO00O-DFFF = Floating Point Package (053 ae 
ECOG=FFFF = Resident Operating System ROM bse. 


Figure 4-1 6502 System Memory Map 


This section will break these regions into even smaller functional 
divisions and provide detailed explanations of their usage. 


RAM REGION 
The OS and the control program share the RAM region. The RAM region 


can be further subdivided into the following sub regions for 
discussion purposes: 


Page 0 = 6502 page zero address mode region. 

Page i = 6502 stack region. 

Pages 2-4 = 0S database and user workspace. 

Pages 53-6 = User program workspace. 

Pages 7-XX = Bootable software area/free RAM. # 

Pages XX-top of RAM = Screen display list and data. # 


# Note that XX is a function of the screen graphics mode and the 
amount of RAM installed. 


The paragraphs that follow describe how the 0S uses RAM subregions, 
and presents user program recomendations. 
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Page 0O 


The architecture of the 6502 microcomputer instruction set and 
addressing modes gives page O special significance. References to 
addresses in that page (O0CO0C to OOFF) are faster, require fewer 
instruction bytes, and provide the only mechanism for hardware 
indirect addressing. Page O should be used sparingly so that all 
possible users can have a- portion of it. The OS permanently takes the 
lower half of page CG (0000 to OO7F). This portion can never be used by 
any outer environment unless the 05 is completely disabled and all 
interrupts to the OS are eliminated. 


The upper half of page O (0080 to OOFF) is available to outer 
environments with the following restriction: the floating point 
package, if used, requires GCOD4 through OOFF. 


Page i 


Page 1 is the 6502 hardware stack region; JSR instructions, PHA 
instructions, and interrupts all cause data bytes to be written to 
page 1. Conversely RTS. PLA. and RTI instructions all cause data bytes 
to be read from page 1. The 256 byte stack is adequate for normal 
subroutine calls plus interrupt process nesting, so no restrictions 
have been made on page i usage. It 15 obvious that a stack of this 
size is totally inadequate for deeply recursive processes or for 
nested processes with large local environments to be saved. So, for 
sophisticated applications, software maintained stacks must be 
implemented. 


The 6502 stack pointer is initialized at power-up or system reset to 
point to location OLFF. The stack then pushes downward toward 0100. 
The stack will wrap around from G100 to OIFF if a stack overflow 
condition occurs, because of the nature of the 6502's G-bit stack 
pointer register. 


0S Data Base 


Locations O200 through O47F are allocated by the OS for working 
variables, tables and data buffers. Portions of this region can be 
used only after you determine that nonconflict with the OS 

is guaranteed. For example, the printer and cassette buffers could be 
used if I/O operations to these devices are impossible within the 
controlling environment. The amount of work involved in determining 
nonconflict seems to be completely out of line with the benefits to be 
gained (except for a few trivial cases) and it is recommended that 
pages 2 through 4 not be used except by the OS. 
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User Workspace 


Locations O480 through OSFF are dedicated for outer environment use 
except when the floating point package is used. The floating point 
package uses locations OS7E through OSFF. 


Boot Region 


Page 7 is the start of the “boot region.“ When software is booted from 
either the diskette or the cassette, it can start at the lowest free 
memory address (that is O700) and proceed upward (although it can also 
start at any address above 0700 and below the screen display list). 
The top of this region defines the start of the “free memory" region. 
When the boot process is complete, a pointer in the data base contains 
the address of the next available location above the software just 
booted. When no software has been booted. this pointer contains the 
Value 6700. 


Screen Display List and Data 


When the OS is handling the screen display. the display list that 
defines the screen characteristics and the current data that is 
contained on the screen are placed at the high address end of RAM. The 
bottom of this region defines the end of the free memory region and 
its location is a function of the screen mode currently in effect. A 
pointer in the data base contains the address of the last available 
location below the screen region. 


Free Memory Region 


The free memory region is all the RAM between the end of the boot 
region and the start of the screen region. The outer level application 
is responsible for managing the free memory region. 


CARTRIDGES A AND B 


There are two SK regions reserved for plug-in cartridges. Cartridge B, 
that is the right-hand cartridge slot found only in the ATARI 800 
Home Computer, has been allocated memory addresses 8000 

through 9FFF. Cartridge A (the left-hand cartridge slot in the ATARI 
800 Computer console, and the only slot in the ATARI 400 Computer 
console} has been allocated memory addresses AQOO through BFFF and 
optionally 8000 through BFFF. for 16K cartridges. If a RAM module is 
plugged into the last slot such as to overlay any of these addresses, 
the RAM takes precedence as long as a cartridge is not inserted. 
However, if a cartridge is inserted, it will disable the entire 
conflicting RAM module in the last slot in 8K increments. 
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MAPPED 1/0 


The 6502 performs input/output operations by addressing the external 
support chips as memory: some chip registers are read/write while 
others are read-only or write-only (the ATARI Home Computer 

Hardware Manual gives descriptions of all of the external registers). 
While the entire address space from DOOO to D7FF has been allocated 
for I/0 decoding, only the following subregions are used: 


DOOO-DOIF = CTIA 
D200-D2iF = POKEY 
D300-D31F = PIA 

D400-D4iF = ANTIC 


Figure 4-2. Mapped 1/0 


RESIDENT OS AND FLOATING POINT PACKAGE ROM 


The region from D800 through FFFF always contains the OS and the 
floating point package. Care should be taken to avoid using any entry 
points that are not guaranteed not to move, to allow for the 
possibility that another, but functionally compatible, OS can be 
generated in the future. The OS contains many vectored entry points at 
the end of the ROM and in RAM that will not move. The floating point 
package is not vectored, but all documented entry points will be 
fixed: Do not use undocumented routines found by scanning the listing. 
A list of the fixed ROM vectors can be found in Appendix J. 


CENTRAL DATA BASE DESCRIPTION 


See Appendix L. 


MEMORY DYNAMICS 


The free memory region is the area between the end of the boot region 
and the start of the screen region. As such, its Limits are variable. 
MEMLO CO2E7] defines the bottom of the free region, and MEMTOP [CO02E5] 
defines the top of the region. This section presents the conditions 
that cause the setup or alteration of these variables. 
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System Initialization Process 


The OS determines the extent of the lowest block of contiguous RAM, 
and saves the limits. The Screen Editor is then opened, thus setting a 
new (and lower} value in MEMTOP. Diskette or cassette-booted software 
might be brought into memory, that would probably set a new (and 
higher} value in MEMLO (see Section 7). MEMLO and MEMTOP will define 
the maximum amount of free memory available when the application 
program finally gets control. That amount of free memory can later 
decrease, as described in the next paragraph. 


Changing Screen Modes 


The Display Handler interprets the variable APPMHI ‘COOOEI]’ to contain 
the address below which MEMTOP cannot extend. This allows you to 
protect the portion of free memory space that you are using from being 
overwritten as a result of screen mode change. The display handler 
will set the screen for mode 0. update MEMTOP, and return an error 
status to you, if it determines that the screen memory will 

extend below APPMHI as a result of a screen mode change. In other 


cases the Display Handler effects the desired mode change and updates 
MEMTOP. 
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9 1/0 SUBSYSTEM 


This section discusses the I/0 subsystem of the Operating System. The 
I/O subsystem comprises a collection of routines that allow you 

to access peripheral and local devices at three different levels. The 
CIO (Central I/0 Utility), provides the highest level, device 
independent access to devices. The second level allows communication 
with the device handlers. The lowest level is the SIO (Serial I/O bus 
Utility) routine. Any lower level access to a device involves the 
direct reading and writing of the hardware registers associated with 
the device. 


The data byte is the basic unit of input/output. A data byte can 
contain either “binary” (non text) information. or encoded text 
information. The text encoding scheme supported by the OS is called 
ATASCII, derived from the words "ATARI ASCII." Most ATASCII codes are 
the same as ASCII, with the primary deviations being the control 
codes. Appendix D shows the ATASCII character set, and Appendices E, 
F, and G show device-specific implementations for the display, 
keyboard, and printer. 


The \structure of the I/0 subsystem is shown on the following page. 
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‘ user ‘ 
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+: Utility : 
+—-————-——-—— + 


Where: ---- shows a control path. #### shows the data structure 
required for a path. 


Note the following: 
o The Keyboard/Display/Screen Editor Handlers don’t use SIO. 
o The Diskette handler cannot be called directly from CIO. 
o The DCB is shown twice in the diagram. 


Figure 5S-i I/O Subsystem Structure Flow Diagram 
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CENTRAL I/0 UTILITY 


The Central I/O Utility provides you with a single interface in which _ 
to access all of the system peripheral devices in a device-independent 

manner. The minimum unit of data transfer is the data byte. The CIO 

also supports multiple byte transfers. All I/O operations are 

performed on a “return-to-user-when-complete" basisi there is no way 

to initiate concurrent “overlapped" I/O processes. 


I/O is organized by “files, " where a file is a sequential 
collection of data bytes. A file can or may not contain textual 
data and it can or may not be organized by “records. “ where a 
record is a contiguous group of bytes terminated by an EDL (End of 
Line) character. Some files are synonymous with a device (as with 
the printer and the Screen Editor), while other devices can contain 
multiple files, each with a unique name (as with the disk drive}. 


CIO allows you to access up to eight independent device/files 

at one time, because there are eight I/0 Control Blocks (IOCB‘’s? in 
the system. Each of the IDCB’s can be assigned to control any 
device/file because there are no preferred assignments. except that 
IOCB #0 is assigned to the Screen Editor at power-up and 

system reset. 


To access a peripheral, you first set up an IOCB for the OPEN 
command, that supplies the system name for the device to be 
accessed (e.g. K:, for the keyboard, P:, for the printer, D: STARS 
for a diskette file named ‘STARS’. etc). You then call the CIO, 
telling it to examine the IOCB to find the OPEN information. CIO 
attempts to find the specified device/file and returns a status 
byte indicating the success of the search. If the specified 
device/file can be found by CIO, then CIO stores control 
information in the IOCB. The IOCB is now used for as long as that 
file is open. 


Once a file is open. it can then be accessed using data-read or 
data-write types of commands; in general, reading can proceed until 
there 1s no more data to read (End of File?) and writing can proceed 
until there is no more medium to store data on (End of Medium), 
although neither reading nor writing need proceed to that point. 
The reading and writing of data generally occurs into and out of 
user-supplied data buffers (although a special case allowing single 
byte transfers using the 6502 A register is provided>. 


When there are no more accesses to be performed on an open 

device/file, you perform the close operation. This 

accomplishes two functions: 

9) It terminates and makes permanent an output file (essential 
for diskette and cassette). 


3) It releases that IOCB to be used for another I/0 operation. 
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CIO Design Philosophy 


The CIO utility was designed specifically to meet the following 
design criteria. 


a) The transfer of data is device independent. 

o Byte-at-a-time, multiple byte and record-aligned accesses are 
supported. 

a) Multiple device/files can be accessed concurrently. 

2) Error handling is largely device independent. 

3) oon device handlers can be added without altering the system 


Device Independence 


CIO provides device independence by having a single entry point for 
all devices (and for all operations?) and by having a 
device-independent calling sequence. Once a device/file is opened, 
data transfers occur with no regard to the actual device involved. 
Uniform rules for handling byte- and record-oriented data transfers 


allow the actual device storage block sizes to be transparent to you. 


Data Access Methods 


The CIO supports two file access methods: byte-aligned and 
record-aligned. 


Byte-aligned accesses allow you to treat the device/file as a 
sequential byte streami any number of bytes can be read or written 
and the following operation will continue where the prior one left 
off. Records are of no consequence in this mode, and reads or 
writes can encompass multiple records if desired. 


Record-aligned accesses allow you to deal with the data stream 

at a higher level, that of the data record or “line of text." Each 
and every write operation creates a single record (by definition?>. 
Each read operation assures that the following read operation 

will start at the beginning of a record. Record-aligned accesses 
cannot deal with portions of more than one record at a time. 
Record-aligned accesses are useful only with text data or with 
binary data guaranteed not to contain the EOL character ($9B) as 
data. 


Note that any file can be accessed using the byte-aligned access 
method, regardless of how the file was created. But not all files 
can be successfully read using record-aligned accesses; the file 
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must contain EOL characters at the end of each record and at no 
other place. 


Multiple Device/File Concurrency 


Up to eight device/files can be accessed concurrently using CIO, 
each operating independently of the others. 


Unified Error Handling 


All error detection and recovery occurs within the CIO subsystem. 
The status information that reaches you is in the form of a 
status byte for each device/file. Error codes are device 
independent as much as possible (see Appendix B>. 


Device Expansion 


Devices are known by single character names such as K or P,. and a 
number of device handlers are part of the resident system ROM. 
However, additional device handlers can be added fo the system 
using the RAM-resident device tablei this is normally done at 
power-up time as with the diskette boot process. but can be done at 
any point in time. 


CIO Calling Mechanism 


The input/output control block (I0CB) is the primary parameter 
passing structure between you and CIO. There are eight IOCB’s 
in the system, arranged linearly in RAM as shown below: 


af me mnie eo aeite + low address [0340] 


pe a + high address 


Figure 5-2 CIO Calling Mechanism 
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One IOCB is required for each open device/file. Any IOCB can be used 
to control any device/file, although IOCB ©O is normally assigned to 
the Screen Editor (E:). You perform a typical I/0 operation by: 


9) Inserting appropriate parameters into an IOCB of your choosing 
0 Putting the IOCB number times 16 into the 6502 X register 
o Performing a JSR to the CIO entry point CIOV CE456]. 


CIO returns to you when the operation is complete or if an 

error was encountered. The operation status is in the IOCB used, as 
well as in the 6502 Y register. The 6502 condition codes will also 
reflect the value in the Y register. In some cases a data byte will 
be in the 6502 A register. The X register will remain unchanged for 


all operations and conditions. An example is shown below: 
IOCB2X = $20 i INDEX FOR IOQCB #€2. 
i DX #IOCB2X 
JSR CIOV 
CPY #0 i Coptional? 
BMI ERROR 


This sector describes each IOCB byte, with its file name and 
address. Each IO0CB is 16 bytes long. Some bytes can be altered by 
you and some are reserved for use by CIO and/or the device 
handlers. 


Handler ID -- ICHID £0340] 


The handler ID is an index into the system device table (see 
Section 9) and is not user-alterable. This byte is set by CIO as 
the result of an OPEN command and is left unchanged until the 
device/file is closed, at that time CIO will set the byte to $FF. 


Device Number -- ICDNO [0341] 


The device number is provided by CIO as the result of an OPEN 
command and is not user-alterable. This byte is used to 


distinguish between multiple devices of the same type, such as 
Di: and Da:. 
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Command Byte -- ICCMD [0342] 


You set the command byte. It specifies the command to be 
performed by the CIO. This byte is not altered by CIO. 


Status -- ICSTA CO343] 


The CIO conveys operation status to you with the command 

status byte as a result of each and every CIO call. Each and 
every CIO call updates the command status byte. The most 
Significant (sign) bit is a one for error conditions and zero for 
non-error conditions, and the remaining bits represent an error 
number. See Appendix B for a list of status codes. 


Buffer Address -- ICBAL [0344] and ICBAH [0345] 


You set this 2-byte pointer; it is not altered by CIO. The 
pointer contains the address of the beginning (low address) of a 
buffer that: 


o Contains data for read and write operations 


o Contains the device/filename specification for the OPEN 
command. 


You can alter the pointer at any time. 


PUT Address -- ICPTL C0346] and ICPTH [0347] 


The CIO sets this 2-byte pointer at OPEN time to the handler’s 
PUT CHARACTER entry point (- 1). The pointer was provided to 
accommodate the people writing the ATARI BASIC cartridge, and has 
no legitimate use in the system. This variable is set to point to 
CiIO’s “IOCB not OPEN" routine on CLOSE, Power-up and 

CSYSTEM: RESET. 


Buffer Length/Byte Count -- ICBLL [CO348] and ICBLH [0349] 


You set this 2-byte count to indicate the size of the data 

buffer pointed to by ICBAL and ICBAH for read and write 
operations. It is not required for OPEN. After each read or write 
operation, CIO will set this parameter to the number of bytes 
actually transferred into or out of the data buffer. For 
record-aligned access, the record length can well be less than 
the buffer length. Also an end of file condition or an error can 
cause the byte count to be less than the buffer length. 


Auxiliary Information -- ICAX1i COG4AJ] and ICAX2 [034B] 
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You set these 2-bytes. They contain information that is 
used by the OPEN command process and/or is device-dependent. 


For OPEN, two bits of ICAX1 are always used to specify the OPEN 
direction as shown below, where R is set fo i for input (read) 
enable and Wis set to i for output (write?) enable. 


+ + 
$ | 
{ { t 


ICAX1 is not altered by CIO. You should not alter ICAX1 
once the device/file is open. 


The remaining bits of ICAX1 and all of ICAX2 contain only 
device-dependent data and are explained later in this section. 


Remaining Bytes (ICAX3-ICAX4) 


The handler reserves the four remaining bytes for processing the 
I/O command for CIO. There is no fixed use for these bytes. They 
are not user-alterable except as specified by the particular 
device descriptions. These bytes will be referred to as ICAXS, 
ICAX4, ICAXS and ICAX6, although there are no equates for those 
names in the OS equate file. 


CIO Functions 


The CIO supports records and blocks and the handlers support 
Single bytes. All of the system handlers support one or more 
of the eight basic functions subject to restrictions based 
upon the direction of data transfer (e.g. one cannot read data 
from the printer}. The basic functions are: OPEN, CLOSE, CET 
CHARACTERS, PUT CHARACTERS. GET RECORD, PUT RECORD, GET STATUS, 
and SPECIAL. 


OPEN -- Assign Device/Filename to IOCB and Ready for Access 


A device/file must be opened before it can be accessed. This 
process links a specific IOCB to the appropriate device 
handler. initializes the device/file, initializes all CIO 
control variables, and passes device-specific options to the 
device handler. 
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You set up the following IOCB parameters prior to calling CIO for an 
OPEN operation: 


COMMAND BYTE = $03 


BUFFER ADDRESS = pointer to a device/filename specification. 


AUX1 


OPEN direction bits, plus device-dependent information. 
AUX2 = device-dependent information. 


After an OPEN operation, CIO will have altered the following IOCB 
parameters: 


HANDLER ID = index to the system device table: this is 
used only by CIO and must not be altered. 


DEVICE NUMBER = device number taken from the device/filename 
specification and must not be altered. 


STATUS = result of OPEN operation; see Appendix B for a list 
of the possible status codes. In general, a negative status 
will indicate a failure to open properly. 


PUT ADDRESS = pointer to the PUT CHARACTERS routine for the 
device handler just opened. 


It is recommended that this pointer not be used. 


CLOSE -- Terminate Access to Device/File and Release IOCB. 

You issue a CLOSE command after you are through accessing a 
given device/file. The CLOSE process completes any pending data 
writes, goes to the device handler for any device-specific 
actions, and then releases the IOCB. 


You set the following IOCB parameter prior to calling 
CIO: 


COMMAND BYTE = $0C 


The CIO alters the following IOCB parameters as a result of the 
CLOSE operation: 


HANDLER ID = $FF 
STATUS = Result of CLOSE operation. 


PUT ADDRESS = pointer to “IOCB not OPEN" routine. 
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GET CHARACTERS -- Read n Characters (Byte-Aligned Access) 
The specified number of characters are read from the device/file 
to the user-supplied buffer. EOL characters have no termination 
features when using this function; there can be no EOL, or many 
EOL ’s, in the buffer after operation completion. There is a 
special case provided that passes a single byte of data in the 
6502 A register when the buffer length is set to zero. 
You set the following IOCB parameters prior fo calling CIO: 
COMMAND BYTE = $07 
BUFFER ADDRESS = pointer to data buffer. 


BUFFER LENGTH = number of bytes to readi if this is zero, 
the data will be returned in the 6502 A register only. 


The CIO alters the following IOCB parameters as a result of the 
GET CHARACTERS operation: 


STATUS = result of GET CHARACTERS operation. 
BYTE COUNT/BUFFER LENGTH = number of bytes read to the 


buffer. The BYTE COUNT will always equal the BUFFER LENGTH 
except when an error or an end-of-file condition occurs. 


PUT CHARACTERS -- Write n Characters (Byte-Aligned Access} 
The specified number of characters are written from the user-supplied 
buffer to the device/file. EOL characters have no buffer 
terminating properties, although they have their standard meaning 
to the device/file receiving them; no EOL ’s are generated by CIO. 
There is a special case that allows a single character to be 
passed to CIO in the 6502 A register if the buffer length is 
zero. 


You set the following IOCB parameters prior to initiating the PUT 
CHARACTERS operation: 


COMMAND BYTE = $0B 
BUFFER ADDRESS = pointer to data buffer. 
BUFFER LENGTH = number of bytes of data in buffer. 


The CIO alters the following IOCB parameter as a result of the 
PUT CHARACTERS operation: 


STATUS = result of PUT CHARACTERS operation. 
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GET RECORD -- Read Up To n Characters (Record-Aligned Access) 


Characters are read from the device/file to the user-supplied 
buffer until either the buffer is full or an EOL character is 
read and put into the buffer. If the buffer fills before an EOL 
is read, then the CIO continues reading characters from the 
device/file until an EOL is read,;, and sets the status to 
indicate that a truncated record was read. No EOL will be put at 
the end of the buffer. 


You set the following IOCB parameters prior to calling CIO: 
COMMAND BYTE = $05 
BUFFER ADDRESS = pointer to data buffer. 


BUFFER LENGTH = maximum number of bytes to read (including 
the ENDL character). 


The CIO alters the following IOCB parameters as a result of the 
GET RECORD operation: 


STATUS = result of GET RECORD operation. 


BYTE COUNT/BUFFER LENGTH = number of bytes read to data 
buffer; this can be less than the maximum buffer length. 


PUT RECORD -- Write Up To n Characters (Record-Aligned Access) 


Characters are written from the user-supplied buffer to the 
device/file until either the buffer is empty or an EOL character 
is written. If the buffer is emptied without writing an EOL 
character to the device/file, then CIO will send an EDL after the 
last user-supplied character. 
You set the following IOCB parameters prior to calling CIO: 

COMMAND BYTE = $09 

BUFFER ADDRESS = pointer to data buffer. 

BUFFER LENGTH = maximum number of bytes in buffer. 


The CIO alters the following IOCB parameter as a result of the 
PUT RECORD operation: 


STATUS = result of PUT RECORD operation. 
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GET STATUS -- Return Device-Dependent Status Bytes 


The device controller is sent a STATUS command, and the 
controller returns four bytes of status information that are 
stored in DVSTAT CO2EA}). 


You set the following [OCB parameters prior to calling CIO: 
COMMAND BYTE = $0D 


BUFFER ADDRESS = pointer to a device/filename specification 
if the IOCB is not already OPEN; see the discussion of the 
implied OPEN option below. 


After a GET STATUS operation, CIO will have altered the following 
parameters: 


STATUS = result of GET STATUS operationi see Appendix B for 
a list of the possible status codes. 


DYSTAT = the four-byte response from the device controller. 


SPECIAL -- Special Function 


Any command byte value greater than $0D is treated by CIO as a 

special case. Since CIO does not know what the function is, CIO 
transfers control to the device handler for complete processing 
of the operation. 


The user sets the following IOCB parameters prior to 
calling CIO: 


COMMAND BYTE > $0D 


BUFFER ADDRESS = pointer to a device/filename specification 
if the IOCB is not already open: see the discussion of the 
implied OPEN option below. 


Other IOCB bytes can be set up, depending upon the specific 
SPECIAL command being performed. 


After a SPECIAL operation, CIO will have altered the following 
parameters: 


STATUS = result of SPECIAL operationi see Appendix B for a 
list of the possible status codes. 


Other bytes can be altered, depending upon the specific 
SPECIAL command. 


OPERATING SYSTEM COi6555 -- Section 9 
45 


Implied OPEN Option 


The GET STATUS and SPECIAL commands are treated specially by CIO; ©} 
they can use an already open [OCB to initiate the process or they 

can use an unopened IO0CB. If the IOCB is unopened, then the 

buffer address must contain a pointer to a device/filename 

specification. just as for the OPEN commandi CIO will then open 

that IOCB, perform the specified command and then close the IOCB 

again. 


Device/Filename Specification 


As part of the OPEN command, the IOCB buffer address parameter 
points to a device/filename specification, that is a string of 
ATASCII characters in the following format: 


<specification> ::= <device>fCi<number>): (<filename>l<eol> 
<device> = CiDiE:KiPiRiS 

<number> = L11:2:1314i5:6:7:8 

<filename> has device-dependent characteristics. 

<eol> ::= $9B 


The following devices are supported at this writing: 


C = Cassette drive 

Di through DS = Floppy diskette drives # 
= Screen Editor 

K = Keyboard 
= 40-column printer 

P2 = 80-column printer # 

Ri through R4 = RS-232-C interfaces # 

S = Screen display 


Devices flagged by asterisks (#} are supported by nonresident 
handlers. 


If <number> is not specified, it is assumed to be 1. 


The following examples show valid device/filename specifications: 


€> Cassette 
D2: BBDAT File “BDAT" on disk drive #2 
D: HOLD File "HOLD" on disk drive #1 
K: Keyboard 
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I/O Example 


The example provided in this section illustrates a simple example of 


an I/O operation using the CIO routine. 


wee Se tee feo 


drive #1. 


This code segment illustrates the simple example of reading 
text lines (records) from a diskette file named TESTER on disk 
All symbols used are equated within the program 
although many of the symbols are in the OS equate file. 


The program performs the following steps: 


Opens the file 


‘Di: TESTER’ using IOCB #3. 


2. Reads records until an error or EOF is reached. 


’ 
# 
i a 
rd 
' 


3. Closes the file. 


i I/O EQUATES 


EOL= $9B i; END OF LINE CHARACTER. 
IOCB3= #30 i IOCB #3 OFFSET (FROM IOCB #0). 
ICHID= #0340 i CHANDLER ID -- SET BY CIO}. 
ICDNO= ICHID+1 i (DEVICE @ =— SET BY CIO}. 
ICCOM= ICDNO+1 i COMMAND BYTE. 

ICSTA= ICCOM+1 i STATUS BYTE -- SET BY CIO. 
ICBAL= ICSTA+1 i BUFFER ADDRESS (LOW). 
ICBAH= ICBAL+i i BUFFER ADDRESS (HIGH). 
ICPTL= ICBAH+i 

ICPTH= ICPTL+1 

ICBLL= ICPTH+1 i; BUFFER LENGTH (LOW). 
ICBLH= ICBLL+1 i BUFFER LENGTH (HIGH). 
ICAX1= ICBLH+1 + AUX 1. 

ICAX2= ICAXiri i AUX 2. 

OPEN= $03 i OPEN COMMAND. 

GETREC= $05 i GET RECORD COMMAND. 

CLOSE= #0C ; CLOSE COMMAND. 

OREAD= %064 i OPEN DIRECTION = READ. 
OWRIT= $08 i OPEN DIRECTION = WRITE. 
EOF= $85 +; END OF FILE STATUS VALUE. 
CiIO0V= $E 456 i CIO ENTRY VECTOR ADDRESS. 


i FIRST INITIALIZE THE [OCB FOR FILE "OPEN". 


LDX #IOCBS3 i; SETUP TO ACCESS IOCB #3. 
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LDA #O0PEN ; SETUP OPEN COMMAND. 


STA ICCOM, X 

LDA #NAME ; SETUP BUFFER POINTER TO ... © 
STA ICBAL, X ; ... POINT TO FILENAME. 

LDA #NAME /256 

STA ICBAH, X 

LDA #OREAD i SETUP FOR OPEN READ. 

STA ICAX1, X 

LDA #0 ; CLEAR AUX 2. 

STA ICAX2, X 


;- “UFEN” THE-FILe. 


JSR Crov i PERFORM "OPEN" OPERATION. 
BPL TP10 i STATUS WAS POSITIVE -- OK. 
JMP ERROR i; NO -- "OPEN" PROBLEM. 


i SETUP TO READ A RECORD. 


TP10 LDA #GETREC ; SETUP “GET RECORD" COMMAND. 
STA ICCOM, X 
LDA #BUFF i; SETUP DATA BUFFER POINTER. 
STA ICBAL, X 
LDA #BUFF/256 
STA ICBAH, X 


LOOP LDA #BUFFSZ i SETUP MAX RECORD SIZE ... 
STA ICBLL., X i... “ROR: TO EVERY REAL. 
LDA #BUFFSZ/256 
STA ICBLH, X 
JSR CTOv +; READ A RECORD. 
BMI TP20 i MAY BE END OF FILE. 
i A RECORD IS NOW IN THE DATA BUFFER “BUFF". IT IS TERMINATED BY @ 
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i AN EOL CHARACTER. AND THE RECORD LENGTH [IS IN “ICBLL" and “ICBLH". 
i THIS EXAMPLE WILL DO NOTHING WITH THE RECORD JUST READ. 


JMP i OOP i READ NEXT RECORD. 


i NEGATIVE STATUS ON READ -- CHECK FOR END OF FILE. 


TP20 CPY #EOF ; END OF FILE STATUS? 
BNE ERROR i NO -- ERROR. 
LDA #CLOSE ;. YES —= tae Ie. 
STA ICCOM, X 
JSR croVv i CLOSE THE FILE. 
JMP + ; ##% END OF PROGRAM ##+# 


i DATA REGION OF EXAMPLE PROGRAM 


' 


@ NAME BYTE “Di: TESTER", EOL 
BUFFSZ= 80 ; 80 CHARACTER RECORD MAX 
(INCLUDES EOL). 
BUFF= + ; READ BUFFER. 
t= #+BUFFSZ 
_ END 


Figure 5-3 An 1/0 Example 
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Device-Specific Information 


This section provides device-specific information regarding the 
device handlers that interface to CIO. 


Keyboard Handler (K: } 


The keyboard device is a read only device with a handler that 
supports the following CIO functions: 


OPEN 

CLOSE 

GET CHARACTERS 

GET RECORD 

GET STATUS (null function?) 


The Keyboard Handler can produce the following error statuses: 


$80 -- (CBREAK] key abort. 
$688 -- end-of-file (produced by pressing CCTRLJ 3). 


The Keyboard Handler is one of the resident handlers. It has a 
set of device vectors starting at location F420. 


The keyboard can produce any of the 256 codes in the ATASCIT 
character set (see Appendix F). Note that a few of the keyboard 
keys do not generate data at the Keyboard Handler level. These 
keys are described below: 


C/i\] - The ATARI key toggles a flag that enables/disables the 
inversion of bit 7 of each data character read. The 
Screen Editor editing keys are exempted from such 
inversion, however. 


CAPS - The CCAPS/LOWR] key provides three functions: 


CSHIFTICCAPS/LOWR] -- Alpha caps lock. 
CCNTRLICCAPS/LOWR] -- Alpha CCTRLI lock. 
C[CAPS/LOWR J ~~ Alpha unlock. 
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The system powers up and will system reset to the alpha 
caps lock option. 


Some key combinations are ignored by the handler. such as 
CCTRLI 4 through CCTRLI Y. CCTRLI O CCTRLI 1, CCTRLI 7/7, and 
all key combinations in that the CSHIFT] and CCTRL] keys are 
depressed simultaneously. 


The CCTRLI 3 key generates an EOL character and returns EOF status. 


The CBREAK] key generates an EOL character and returns BREAK status. 


CIO Function Descriptions 


The device-specific characteristics of the standard CIO functions 
(described earlier in this section) are detailed below: 


OPEN 


The device name is K, and the handler ignores any device number 
and filename specification, if included. 


There are no device-dependent option bits in AUX1 or AUXe2. 


CLOSE 


No special handler actions. 


GET CHARACTERS and GET RECORD 


The handler returns the ATASCII key codes to CIO as they are 
entered, with no facility for editing. 


GET STATUS 


The handler does nothing but set the status to $01. 


Theory of Operation 


Pressing a keyboard key generates an IRQ interrupt and vectors to 
the Keyboard Handler’s interrupt service routine (see Section 6). 
The key code for the key pressed is then read and stored in data 
base variable CH CO2FC]. This occurs whether or not there is an 
active read request to the Keyboard Handler. and effects a one-byte 
FIFO for keyboard entry. See Appendix L (ES) for a discussion of 
the auto repeat feature. 
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The Keyboard Handler monitors the CH variable for not containing 
the value $FF (empty state) whenever there is an active read 
request for the handler. When CH shows nonempty, the handler 
takes the key code from CH and sets CH to $FF again. The key code 
byte obtained from CH is not an ATASCII code and has the 
following form: 


1 if the CCTRL] key is pressed. 
1 if the CSHIFT] key is pressed. 


8 
Ht fl 


The remaining six bits are the hardware key code. 


The key code obtained is then converted to ATASCII using the 
first of the following rules that applies: 


Ignore the code if the C and S bits are both set. 

If the C bit is set, process the key as a CCTRLI code. 

If the S bit is set, process the key as a CSHIFT] code. 

If CCTRLI lock is in effect, process alpha characters as CTRL 

codes, all others as lowercase. 

2. IF €SHIFTI lock is in effect. process alpha characters as SHIFT 
codes, all others as lowercase. 

&. Else, process as lowercase character. 


stadt ale me 


Then: If the resultant code is not a Screen Editor control code, 
and if the video inverse flag is set, then set bit 7 of the 
ATASCII code (will cause inverse video when displayed>. 
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KEY CODE TO ATASCII CONVERSION TABLE 


Key Key Lwr. €SHIFTJ] (CCTRLI Key Key Lwr. SHIFT CTRL 


Code Cap Case Code Cap Case 

00 & 6C 4C OC 20 ' 2C 2B 60 
O1 J 6A 44 OA 21 SPACE 20 20 20 
C2 i 3B 3A 7B 2 2E oD &0 
O03 —— me saa mene eo N 6E 4E OE 
O4 om ae sent as 24 wast: ane es ee 
OS K 6B 4B OB 2o M &D 4D OD 
06 + 2B oC 1E 2S / er oF meee 
O07 # 2A 9E iF a7 fin ons = seg 
08 O OF 4F OF 28 R 72 v2 i2 
OF ee mon ses aia a> ee pate: — a 
OA P 70 20 10 aA = 63 45 OS 
OB U 793 whe 15 =B 5 77 09 19 
Oc RET 9B 9B 9B 2C TAB fa a OF TE 
OD I &9 49 09 =D T 74 04 14. 
OE 2D oF 1c ee W 77 o7 17 
OF = 3D 7C 1D oF Q 71 21 il 
i0 Vv 76 26 16 30 4 39 28 — 
il oem ate one ane oi one anne si eee 
ie C 63 43 O03 32 0 30 a9 see 
i3 oon oe a — a3 7 37 27 ae 
14 —— —— “— = 34 BACKS 7E 9C FE 
iS B 62 42 O02 39 8 38 40 ais: 
14 X 78 78 18 3& < 3G 7D 7D 
17 Z 7A oA 1A a7 2 GE 7D FF 
is at 34 24 ss 38 ig 6&4 4& O04 
19 — oe ~<a nie 37 H 68 48 08 
1A 3 33 23 9B 3A D 64 44 O4 
1B & 34 2h <i 3B rie — sn sos 
ic fESC] 1B iB iB 3c Cars == ee a 
1D 2 35 ao ne 3D G &7 47 07 
iE 2 32 ae FD JE. =) 73 03 13 
iF 1 Si ai oe OF A Gi 41 Ol 


%# CCTRLI 3G returns EDF status. 


A complement of this table (ATASCII to keystroke} is given in 
Appendix F. 


Figure 5-4 Keycode to ATASCII Conversion Table 


OPERATING SYSTEM CO1i6555 -- Section 5 


ore 


Display Handler (S: } 


The display device is a read/write device with a handler 
that supports the following CIO functions: 


OPEN 

CLOSE 

GET CHARACTERS 

GET RECORD 

PUT CHARACTERS 

PUT RECORD 

GET STATUS (null function) 
DRAW 

FILL 


The Display Handler can produce the following error statuses: 


$84 -- Invalid special command. 

$8D -- Cursor out-of-range. 

$71 -- Screen mode > 11. 

$93 -- Not enough memory for screen mode selected. 


The Display Handler is one of the resident handlers, and 
therefore has a set of device vectors starting at location E410. 


Screen Modes 


You can operate the display screen in any of 20 

configurations (modes i through 8 with or without split 
screeni plus mode 0. and modes 9 through 11 without split 
screen). Mode O is the text displaying mode. Modes i through 
ii are all graphics modes (although modes 2 and 3 do display a 
subset of the ATASCII character set). Modes FY through 11 
requite a GTIA chip to be installed in place of the standard 
CTIA chip. 


TEXT MODE © 


In text mode O the screen is comprised of 24 lines of 40 
characters per line. Program alterable left and right margins 


limit the display area. They default to 2 and 39 (of a possible 0O 


and 39>}. 
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A program-controllable cursor shows the destination of the next 
character to be output onto the screen. The cursor is visible as 
the inverse video representation of the current character at the 
destination position. 


The text screen data is internally organized as variable length 
logical lines. The internal representation is 24 lines when the 
screen is cleared. Each EOL marks the end of a logical line as 
text is sent to the screen. If more than 3 physical lines of text 
are sent, a logical line will be formed every 3 physical lines. 
The number of physical lines used to comprise a logical line (1 
to 3) is always the minimum required to hold the data for that 
logical line. 


The text screen “scrolls" upward whenever a text line at the 
bottom row of the screen extends past the right margin, or a text 
line at the bottom row is terminated by an EOL. Scrolling removes 
the entire logical line that starts at the top of the screen, and 
then moves all subsequent Lines upward to fill in the void. The 
cursor also moves upward, if the logical line deleted exceeds one 
physical line. 


All data going to or coming from the text screen is represented 
in 68-bit ATASCII code as shown in Appendix E. 


TEXT MODES 1 AND 2 


In text modes i and 2 the screen comprises either 24 lines of 20 
characters (mode 1), or 12 lines of 20 characters (mode 2). The 
left and right margins are of no consequence in these modes and 
there is no visible cursor. There are no logical lines associated 
with the data and in all regards these modes are treated as 
graphics modes by the handler. 


Data going to or coming from the screen is in the form shown 
below: 


7 0 
Steals arta date aeetuahenie teats dee tei 
aes ee D { 
+—-+—-+4+—-4+-4+-4—-4-4-4 


Where: C is the color/character-set select field 
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Color Color Character Character 


Value (default) Register Set Set 

(see CHBAS=$E0 CHBAS=$E2 

Appendix 

H } 

0 green (PF1) bra ean ae CHEART] CARROW] 
i gold (PFO) eee cet 2 CHEARTI] CARROW] 
4 gold (PFO) et Sse CDIAMONDICTRIANGLE J 
3 green (PF i> aa ae CDIAMONDICTRIANGLE J 
4 red (PFS) ee CHEART] CARROW] 
me blue (PF2) > ae CHEART J CARROW] 
6 blue (PF2) ER ee CDIAMONDICTRIANGLE J 
7 red (PFS) ee CDIAMONDICTRIANGLE J 


Dis a S-bit truncated ATASCII code that selects the specific 
character within the set selected by the C field. See Appendix E 
for the graphics representations of the characters. 


Data base variable CHBAS (O2F4] allows for the selection of 
either of two data sets. The default value of $EG provides the 
capital letters, numbers and punctuation characters; the 
alternate value of $E2 provides lowercase letters and the special 
character graphics set. 


Figure 5-5 Text Modes 1 and 2 Data Form 


GRAPHICS MODES (Modes 3 Through 11) 


The screen has varying physical characteristics for each of the 
graphics modes as shown in Appendix H. Depending upon the mode, a 
i to 16 color selection is available for each pixel and the 
screen size varies from 20 by 12 (lowest resolution) to 320 by 
192 (highest resolution) pixels. 


There is no visible cursor for the graphics mode output. 


Data going to or coming from the graphics screen is represented 
as 1 to &—-bit codes as shown in Appendix H and in the GET/PUT 
diagrams following. 


SPLIT-SCREEN CONFIGURATIONS 


In split-screen configurations, the bottom of the screen is 
reserved for four lines of mode O text. The text region is 
controlled by the Screen Editor, and the graphics region is 
controlled by the Display handler. Two cursors are maintained in 


this configuration so that the screen segments can be managed 
independently. 
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To operate in split-screen mode. the Screen Editor must first be 
opened and then the Display Handler must be opened using a 
separate IOCB (with the split-screen option bit set in AUX1)>}. 


CIO Function Descriptions 


The device-specific characteristics of the standard CIO functions 
(described earlier in this section) are detailed below: 


OPEN 


The device name is S, and the handler ignores any device number ani 
filename specification, if included. 


The handler supports the following options: 


+ 
AUX1 ‘ 
+ 


1 indicates to inhibit screen clear on OPEN. 

1 indicates to set up a split-screen configuration (for 
modes i through & only?. 

R and W are the direction bits (read and write>. 


Where: 


7 O 
HH 

AUX2 ‘ i mode i 
op mp me mp pH 


Where: mode is the screen mode (0 through il}. 


Note: If the screen mode selected is 0, then the AUXI C and 
S options are assumed to be O. 


You share memory utilization with the Display Handler 
information. Sharing is necessary because the Display Handler 
dynamically allocates high address memory for use in generating 
the screen display, and because different amounts of memory are 
needed for the different screen modes. Prior to initiating an 
OPEN command the variable APPMHI COOCE] should contain the 
highest address of RAM you need. The Screen handler 

will open the screen only if no RAM is needed at or below that 
address. 


Upon return from a screen OPEN, the variable MEMTOP CO2E5S] will 
contain the address of the last free byte at the end of RAM 
memory prior to the screen-Trequired memory. 
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As a result of every OPEN command. the following screen variables 
are altered: 


The text cursor is enabled (CRSINH = 0). The tabs are set to 
the default settings (2 and 39). The color registers are set 
to the default values (shown in Appendix H}. 
Tabs are set at positions 7,15, 23, 31,39, 
47,55, 63, 71, 79, 87, 95, 103, 111,119. 

CLOSE 


No special handler actions. 


GET CHARACTERS and GET RECORD 


Returns data in the following screen mode dependent forms, where 
each byte contains the data for one cursor position (pixel); there 
is no facility for having the handler return packed graphics data. 


7 0 
+ — 4 HH HH 
H ATASCII H Mode 0 
+—+— + — + — + — 4 — + HF 
$= + — FH 4 HH + 
ee ~ H D H Modes 1,2 -~- C = color/data 
$$ — 4 — $$ 4 4H set. 


D = truncated ATASCII. 


color. 


+ 
js Sees Modes 3,.5,7 -- B 
+ 


+ +—+ 
H zero iDt Modes 4,4,8 -- B 
+ +—+ 


color. 


am op me 
Modes 9,10,1i1 -- DBD = data. 


+0 + 


— op 
Figure 5-6 Graphics Mode 3-11 GET Data Form 
The cursor moves to the next position as each data byte is 


returned. For mode O, the cursor will stay within the specified 
margins; for all other modes, the cursor ignores the margins. 
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PUT CHARACTERS and PUT RECORD 


& The handler accepts display data in the following screen mode 
dependent formsi there is no facility for the handler to receive 
graphics data in packed form. 


7 0 
+ — + — 4H — + — HHH 
: ATASCII H Mode © 
eee ee ee ee er a oe eos 
+— + — 4 — HH 
Sas H D : Modes i,2 -- C = color/data 
+— + — + — 4 — + — + — HH H+ set, 
DB = truncated ATASCII. 

+ — — + — 4 — + — 4 — HH HH 

H + i 2-4 Modes 3,.5,7 -- DB = color. 
+— b+ — 4 — 4H — $F — HH 
$b — HH HH 

H 4 iDi Modes 4,6,8 -- DB = color. 
+— + — $+ —- 4 — + $+ — + — + + 
+$—+— + — 4 — + — 4 — + HH 

‘ 7 } D H Modes 9,10,11 -- BD = data. 
+ 4 — HH HH 


Figure 5-7 Graphics Mode G-il PUT Data Form 


NOTE: For all modes, if the output data byte equals $9B (EOL), that 
byte will be treated as an EOL characteri and if the output 

data byte equals $7D (CLEAR) that byte will be treated as a 
screen-clear character. 


The cursor moves to the next cursor position as each data byte is 
written. For mode 0. the cursor will stay within the specified 
margins: for all other modes, the cursor ignores the margins. 


While outputting, the Display Handler monitors the keyboard to 
detect the pressing of the CCTRLJ] 1 key combination. When this 
occurs, the handler loops internally until that key combination 
is pressed again: This effects a stop/start function that 
freezes the screen display. Note that there is no ATASCII code 
associated with either the CCTRL] 1 key combination or the 
start/stop function. The stop/start function can be controlled 
only from the keyboard (or by altering database variable CH as 
discussed in Appendix L, E4). 
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GET STATUS 


No handler action except to set the status to $01. 


DRAW 


This special command draws a simulated “straight" line from the 
current cursor position to the location specified in ROWCRS 
CO0S4] and COLCRS (C0055). The color of the line is taken from the 
last character processed by the Display Handler or Screen Editor. 
To force the color, store the desired value in ATACHR CO2FB]. At 
the completion of the command, the cursor will be at the location 
specified by ROWCRS and COLCRS. 


The value for the command byte for DRAW is $11. 


iss 


This special command fills an area of the screen defined by two 
lines with a specified color. The command is set up the same as 
in DRAW, but as each point of the line is drawn, the routine 
scans to the right performing the procedure shown below (in 
PASCAL notation): 


WHILE PIXEL CROW, COL] = O DO 
BEGIN 
PIXEL CROW, COL] := FILDAT; 
COL. := COL + Li 
IF COL > Screen right edge THEN COL := 0 
END; 


An example of a FILL operation is shown below: 


Where: ‘-’ represents the fill operation. 
‘+’ are the line points, with ‘+’ for the endpoints. 


“~- set cursor and plot point. 

—-- set cursor and BRAW line. 

set cursor and plot point. 

—-—- set fill data value, set cursor, and FILL. 


-&WM 
i 
| 
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FILDAT CO2FD] contains the fill data, and ROWCRS and COLCRS 
contain the cursor coordinates of the line endpoint. The value 
in ATACHR CO2FB] will be used to draw the line: ATACHR always 
contains the last data read or written, so if the steps above 
are followed exactly, ATACHR will not have to be modified. 


The value for the command byte for FILL is #12. 


User-Alterable Bata Base Variables 


Certain functions of the Display Handler require you to 

examine and/or alter variables in the OS database. The following 
describes some of the more commonly used handler variables. (see 
Appendix L, Bi-SS. for additional descriptions >}. 


Cursor Position 


Two variables maintain the cursor position for the graphics 
screen or mode O text screen. ROWCRS [0054] maintains the display 
row number: and COLCRS [0055] maintains the display column 
number. Both numbers range from O to the maximum number of 
rows/columns, ~- 1. The cursor can be set outside of the defined 
text margins with no ill effect. You can read and write this 
region. The home position (G,0) for both text and graphics is the 
upper left corner of the screen. 


ROWCRS is a single byte. COLCRS is maintained at e-bytes. with 
the least significant byte being at the lower address. 


When you alter these variables, the screen representation 
of the cursor will not move until the next I/O operation 
involving the display is performed. 


Inhibit/Enable Visible Cursor Display 


You can inhibit the display of the text cursor on the screen 
by setting the variable CRSINH [CO2FO] to any nonzero value. 
Subsequent I/0 will not generate a visible cursor. 


You can enable the display of the text cursor by setting 
CRSINH to zero. Subsequent I/O will then generate a visible 
cursor. 


Text Margins 


The text screen has user-alterable left and right margins. The OS 
sets these margins to 2 and 39. The variable LMARGN ([O00S2] 
defines the left margin, and the variable RMARGN (COOS3] defines 
the right margin. The leftmost margin value is © and the 
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rightmost margin value is 39. 


The margin values inclusively define the useable portion of the 
screen for all operations in that you do not explicitly 

alter the cursor location variables as described prior to this 
paragraph. 


Color Control 


The OS updates hardware color registers using data from the OS 
data base as part of normal Stage 2 VBLANK processing (see Section 


&}. 
register names, 


for the mode dependent uses for the registers. 


Data Base 


COLORO 
COLOR 1 
COLOR2 
COLORS 
COLOR4 


PCOLRO 
PCOLR1 
PCOLR2 
PCOLR3 


Hardware 


COLPFO 
COLPFi 
COLPF2 
COLPFS 
COLBK 


COLPMO 
COLPM1 
COLPM2 
COLPM3 


Theory of Operation 


Function 


PFO 
PF1 
PF2 
PF3 
BAK 


PMO 
PM1 
PM2 
PMS 


Playfield 
Playfield 
Playfield 
Playfield 
Playfield 


0 
1. 
2. 
3 
b 


Shown below are the data base variable names, the hardware 
and the function of each register. See Appendix H 


ackground. 


Player/missile 0 
Player/missile 1. 
Player/missile 2. 
Player/missile 3 


The Display Handler automatically sets up all memory resources 
required to create and maintain the screen display at OPEN time. 
The screen generation hardware requires that two distinct data 
areas exist for graphics modes: 


screen data region. 


i> a display list and 2) a 
Aa third data area must exist for text modes. 


This data area defines the screen representation for each of the 
Consult the ATARI Home Computer 
Hardware Manual for a complete understanding of the material that 


text characters. 


is to follow. 
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The simplified block diagram below shows fhe relationships 
between the memory and hardware registers used to set up a screen 
display (without player/missile graphics) by the OS Note that 

the hardware registers allow for many other possibilities. 


DATA BASE HARDWARE 
VARIABLE REGISTER 
(Updated every 
VBLANK } 
$e + 
i MEMTOP H 
+ + 
5 ee + 
ne + 
Bn nr rn rrr ee + 
ee ee ee SO + on + | 
1 Display {| { SDLSTL i: ‘> DE Tete. $24 
H List i + $e + mt 
= = {| SDLSTH : i DLISTH | 
+—————— + +—---—- + eee + 
: Is totententeateetenenteni + 
: Screen Data i<-- SAVMSC 
= = + + 
i Graphics { H 
i: and/or fo beer ne + 
H Text t 
she + 
End of RAM memory 
+—-----— ~~ + 
H $e > Shane ener een + i 
H i CHBAS=EO i--->! CHBASE +----- + 
f +-——-—- + 0 eee + 
os tome a + 
+ Specials andi EOOO 
i Numbers { 
i + 
i Capital i E100 
i Letters H 
See + 
i Special : E200 
i Graphics i 
+————— + 
( Lowercase 1 E300 
i Letters ‘ 
+————-— + 
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$e + foam + 
: COLOR O ! ! COLPFO | 
= =-->! COLPF1 } 
: COLOR 1} | COLPF2 | 
P<COLOR-2.i =) OLPES -1 
Coie 3S + = GOLaK . t 
: COLOR 4 | 9 +--------- + 
+—-—---- + 


Figure 5-8 Screen Display Block Diagram 


The following relationships are present in the preceding diagram: 


1. 
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Data base variables SDLSTL/SDLSTH contain the address of 
the current display list. This address is stored in the 
hardware display list address registers DLISTL and DLISTH 
as part of the VBLANK process. 


The display list itself defines the characteristics of the 
screen to be displayed and points to the memory containing 
the data to be displayed. 


Data base variable CHBAS contains the MSB of the base address 
of the character representations for the character data (text 
modes only}. 


The default value for this variable is $EO. This variable 
declares that the character representations start at memory 
address EQOO (the character set provided by the OS in ROM}. 
Each character is defined as an 8X8 bit matrix, requiring & 
bytes per character. 1024 bytes are required fo define the 
largest set, since a character code contains up to 7 
Significant bits (set of 128 characters). The OS ROM contains 
the default set in the region from EOOO to ESFF. 


All character codes are converted by the handler from ATASCII 
to an internal code (and vice versa), as shown below: 


ATASCII INTERNAL 
CODE CODE 
OO-1F 40-SF 
20-3F OO-1F 
40-SF 20-3F 
40-7F 60-7F 
B0-9F CO-DF 
AO-BF 80-9F 
CO-—DF AQ-BF 
EOQ-FF EO-FF 
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The character set in ROM is ordered by internal code order. Three 
considerations differentiate the internal code from the external 
(ATASCII>}> code: 


ATASCII codes for all but the special graphics characters were to 
be similar to ASCII. The alphabetic, numeric, and punctuation 
character codes are identical to ASCII. 


In text modes i and 2 it was desired that one character subset 
include capital letters, numbers, and punctuation and the other 
character subset include lowercase letters and special graphics 
characters. 


The codes for the capital and lowercase letters were to be 
identical in text modes 1 and 2. 


Database variables COLORO through COLOR4 contain the current 
color register assignments. Hardware color registers receive 
these values as part of the stage 1 VBLANK process. thus 
providing synchronized color changes (see Appendix H?. 


Database variable SAVMSC points to the lowest memory address of 
the screen data region. It corresponds to the data displayed at 
the upper left corner of the display. 


When the Display Handler receives an open command, it first 
determines the screen mode from the OPEN IOCB. Then it allocates 
memory from the end of RAM downward (as specified by data base 
Variable RAMTOP), first for the screen data and then for the 
display list. The screen data region is cleared and the display 
list is created if sufficient memory is available. The display 
list address is stored to the database. 
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Screen Editor (E: 3} 


The Screen Editor is a read/write handler that uses the Keyboard 
Handler and the Display Handler to provide “line-at-a-time" input 
with interactive editing functions, as well as formatted output. 


The Screen Editor supports the following CIO functions: 


OPEN 

CLOSE 

GET CHARACTERS 

GET RECORD 

PUT CHARACTERS 

PUT RECORD 

GET STATUS (null function? 


See Keyboard Handler and Display Handler Sections for a 
discussion of Screen Editor error statuses. 


The Screen Editor is one of the resident handlers, and 
therefore has a set of device vectors starting at location 
E400. 


The Screen Editor is a program that reads key data from the 
Keyboard Handler and sends each character to the Display Handler 
for immediate display. The Screen Editor also accepts data from 
you to send to the Display Handler, and reads data from the 
Display Handler (not the Keyboard Handler) for you. In fact, 

the Keyboard Handler, Display Handler, and the Screen Editor are 
all contained in one monolithic hunk of code. 


Most of the behaviors already defined for the Keyboard Handler 
and the Display Handler apply as well to the Screen Editor: The 
discussions in this Section will be limited to deviations from 
those behaviors, or to additional features that are part of the 
Screen Editor only. The Screen Editor deals only with text data 
(screen mode ©}. This Section also explains the split-screen 
configuration feature. 


The Screen Editor uses the Display Handler to read data from 
graphics and text screens on demand. You use the Screen 

Editor to determine when the program will read Screen data, and 
where upon the screen the data will be read from. You 

first locates the cursor on the screen to determine the screen 
area to be readi you then press the CRETURN] key fo determine 
when the program will begin to read the data indicated. 
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When the CRETURN] key is pressed, the entire logical line within 
that the cursor resides is then made available to the calling 
program: Trailing blanks in a logical line are never returned as 
data, however. After all of the data in the Line has been sent to 
the caller (this can entail multiple READ CHARACTERS functions if 
desired), an E0L character is returned and the cursor is 


positioned to the beginning of the logical line following the one 
just read. 


CIO Function Descriptions 


The device-specific characteristics of the standard CIO 
functions are detailed below: 


OPEN 


The device name is E, and the Screen Editor ignores any 
device number and filename specification, if included. 


The Screen Editor supports the following option: 


+ 
AUX1 
+ 


Where: R and W are the direction bits (read and write). 
F = 1 indicates that a “forced read“ is desired (see GET 
CHARACTER and GET RECORD for more information). 


CLOSE 


No special handler actions. 


GET CHARACTER and GET RECORD 


Normally the Screen Editor will return data only when you press the 
CRETURN] key at the keyboard. However, the “forced read" OPEN option 
allows you to read text data without intervention. When you command a 
READ operation, the Screen Editor will return data from the start of 
the logical line in which the text cursor is located, and then 

move the cursor to the beginning of the following logical line. A 


read of the last logical line on the screen will cause the screen 
data to scroll. 


A special case occurs when characters are output without a 
terminating EOL, and then additional characters are appended to 
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that logical line from the keyboard. When the CRETURN] key is 
pressed, only the keyboard entered characters are sent to the 
caller, unless the cursor has been moved out of and then back 
into the logical line, in that case all of the logical line will 
be sent. 


PUT CHARACTER and PUT RECORD 


The Handler accepts ATASCII characters as one character per byte. 
Sixteen of the 256 ATASCII characters are control codesi the EOL 
code has universal meaning, but most of the other control codes 
have special meaning only fo a display or print device. The 
Screen Editor processing of the ATASCII control codes is 
explained below: 


CLEAR (#7D} -- The Screen Editor clears the current display of 
all data and the cursor is placed at the home position (upper 
left corner of the screen}. 


CURSOR UP ($1C} -- The cursor moves up by one physical line. The 
cursor will wrap from the top line of the display to the bottom 
line. 


CURSOR DOWN (%$1D) -- The cursor moves down by one physical line. 
The cursor will wrap from the bottom line of the display to the 
top line. 


CURSOR LEFT ($1&} -- The cursor moves left by one column. The 
cursor will wrap from the left margin of a line to the right 
margin of the same line. 


CURSOR RIGHT ($1F) -- The cursor moves right by one column. “The 
cursor will wrap from the right margin of a line to the left 
margin of the same line. 


BACKSPACE ($7E) -- The cursor moves left by one column (but never 
past the beginning of a logical line), and the character at that 
new position is changed to a blank (#20). 
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SET TAB ($9F) -- The Screen Editor establishes a tab point at the 
logical line position at that the cursor is residing. The logical 
line tab position is not synonymous with the physical line column 
position since the logical line can be up to 3 physical lines in 
length. For example, tabs can be set at the i5th, 30th, 45th, 
60th and 75th character positions of a logical line as shown 
below: 


O02 9 19 29 39 Screen column #. 
eee aca cae occa Se i ce et Na area R L/R = margins. 
eo ai miaaiag reales Seer i ne aaa ae SS A logical line. 
eae SS en ei seca ammeter saat tel. = x = inaccesible 
SE Se a er Se eee ener ene ema anes Aenea ne ge columns. 


Note the effect of the left margin in defining the limits of the 
logical line. 


The Handler default tab settings are shown below: 


02 9 19 a9 39 Screen column #. 
weit salnagneer ina $a $e renter atin emo R L/R = margins. 
25s eer Lee soa Se eeceaens b Sensor ssa oats i A logical line. 
Ego Se es dp capers i ee mag i Fa ccacmts  some T x = inaccesible 
Samiti ie cae mrtg a eae 3 Senaeiens- as atces T columns. 
CLEAR TAB ($9E} -- The Screen Editor clears the current cursor 


position within the logical line from being a tab point. There is 
no “clear all tab points" facility provided by the Handler. 


TAB (#7F} -- The cursor moves to the next tab point in the 
current logical line, or to the beginning of the next Line if no 
tab point is found. This function will not increase the logical 
line Length to accommodate a tab point outside the current length 
(e.g. the logical line length is 38 characters and there is a tab 
point at position 350}. 


INSERT LINE ($9D} -- All physical lines at and below the physical 
line in that the cursor resides, are moved down by one physical 
line. The last logical line on the display can be truncated as a 
result. The blank physical line at the insert point becomes the 
beginning of a new logical line. A logical line can be split into 
two logical lines by this process, the last half of the original 
logical line being concatenated with the blank physical line 
formed aft the insert point. 
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DELETE LINE ($9C} -- The logical line in that the cursor resides 
is deleted and all data below that line is moved upward to fill 
the void. Empty logical lines are created at the bottom of the 
display. 


INSERT CHARACTER ($FF)} -- All physical characters at and behind 
the cursor position on a logical line are moved one position to 
the right. The character at the cursor position is set to blank. 
The last character of the logical line will be lost when the 
logical line is full and a character is inserted. The number of 
physical lines comprising a logical line can increase as a result 
of this function. 


DELETE CHARACTER ($FE} -- The character on which the cursor 
resides is removed, and the remainder of the logical line to the 
right of the deleted character is moved to the left by one 
position. The number of physical lines composing a logical line 
can decrease as a result of this function. 


ESCAPE ($1B} --— The next non-EQOL character following this code is 
displayed as data, even if it would normally be treated as a 
control code. The sequence CESCICESC] will cause the second CESC] 
character to be displayed. 


BELL ($FD) -- An audible tone is generatedi the display is not 
modified. 


END OF LINE ($9B} -- In addition to its record termination 
function, the EOL causes the cursor to advance to the beginning 
of the next logical line. When the cursor reaches the bottom line 
of the screen, the receipt of an EOL will cause the screen data 
to scroll upward by one logical line. 


GET STATUS 


The Handler takes no action other than to set the status to $01. 


User-Alterable Data Base Variables 


Also see the Display Handler data base variable discussion. 
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Cursor Position 


When in a split-screen configuration, ROWCRS and COLCRS are associated 
with the graphics portion of the display and two other variables, 
TXTROW C0290] and TXTCOL (O291]. are associated with the text window. 
TXTROW is a single byte, and TXTCOL is @-bytes with the least 
Significant byte being at the lower address. Note that the most 
Significant byte of TXTCOL should always be zero. 


The home position (0,0) for the text window is the upper left corner 
of the window. 


Enable/Inhibit of Control Codes in Text 


Normally all text mode control codes are operated upon as received, 
but sometimes it is desirable to have the control codes displayed as 
if they were data characters. This is done by setting the variable 
DSPFLG CO2FE] to any nonzero value before outputting the data 
containing control codes. Setting DSPFLG to zero restores normal 
processing of fext control codes. 


OPERATING SYSTEM CO016555 -- Section § 
71 


Cassette 


Handler (C: } 


The Cassette device is a read or write device with a Handler 
that supports the following CIO functions: 


OPEN 
CLOSE 


GET CHARACTERS 

GET RECORD 

PUT CHARACTERS 

PUT RECORD 

GET STATUS (null function) 


The Cassette Handler can produce the following error statuses: 


$80 -- 
$84 -- 
oo 
$B8A-90 


CBREAK] key abort. 

Invalid AUXi byte on OPEN. 
end-of-file. 

~- S10 error set (see Appendix C}. 


The Cassette Handler is one of the resident handlers, and therefore 
has a set of device vectors starting at location E440. 


CIO Function Descriptions 


The device- 


specific characteristics of the standard CIO functions are 


detailed below: 


OPEN 


The device 


name is C, and the Handler ignores any device number and 


filename specification, if included. 


The Handler supports the following option: 
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7 6) 

+ +—4—4— 4-4-4 —-4-—-4+ 

AUX2 ici t 
+o bo t— p44 $4 + 


Where: C = i indicates that the cassette is to be read/written without 
stop/start between records (continuous mode}. 


Opening the cassette for input generates a single audible tone, as a 
prompt for you to verify that the cassette player is set up 

for reading (power on; Serial Bus cable connectedi tape cued to start 
of file; and PLAY button depressed). When the cassette is ready, 

you can press any keyboard key (except CBREAKI]>) to initiate tape 
reading. 


Opening the cassette for output generates two closely spaced audible 
tones, as a prompt for you to verify that the cassette player 

is set up for writing (as above, plus RECORD button depressed). When 
the cassette is ready, you can press any keyboard key (Cexcept 

CBREAKI} to begin tape writing. There is no way for the computer to 
verify that the RECORD or PLAY button is depressed. It is possible for 
the file not to be written. with no immediate indication of this fact. 


There is a potential problem with the cassette in that when the 
cassette is opened for writing, the motor keeps running until the 
first record (128 data bytes) is written. If 128 data bytes are 
written or the cassette is closed within about SO seconds of the OPEN, 
and no other serial bus I/0 is performed, then there is no problem. 
However, if those conditions are not met, some noise will be written 
to the tape prior to the first record and an error will occur when 
that tape file is read later. If lengthy delays are anticipated 
between the time the cassette file is opened and the time that the 
first cassette record (128 data bytes) is written, then a dummy record 
should be written as part of the filei typically 128 bytes of some 
innocuous data would be written, such as all zeros, all $FFs, or all 
blanks ($20). 


The system sometimes emits whistling noises after cassette I/O has 
occurred. The sound can be eliminated by storing $03 to SKCTL CD2OF], 
thus bring POKEY out of the two-tone (FSK}) mode. 
CLOSE 
The CLOSE of a tape read stops the cassette motor. 
The CLOSE of a tape write does the following: 
Writes any remaining user data in the buffer to tape. 


Writes an end-of-file record. 
Stops the cassette motor. 
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GET CHARACTERS and GET RECORD 
The Handler returns data in the following format: 


7 0 
5 lente aiendaaieniasieni aie adencaees meas 
t data byte ‘ 
Saale adn saicatenia sien aed ae a 


PUT CHARACTERS and PUT RECORD 
The Handler accepts data in the following format: 


7 e) 
Fe aes ees ele ee eee ee ee 
H data byte 
Oe tees ees ee ne 


The Handler attaches no significance to the data bytes 
written, a value of $97B (EOL) causes no special action. 


GET STATUS 


The Handler does no more than set the status to $01. 


Theory of Operation 


The Cassette Handler writes and reads all data in fixed-length records 
of the format shown below: 


S taaks siete ae damian seat eae 
io to } @ t--O-23 Speed measurement bytes. 
Seta shade einai diem ae aati 
(O30 £-0 1-09.33 
Se oe ee ee a es ee 
control byte : 
ee ee ae ee ee ee ee 
128 
data = 
bytes H 
Sat shea saul aienia dais dei aaa sei 
checksum i (Managed by SIO. not the 
ttt — tt 4—4—4+—4+ Handler. } 


a oe oe 


Figure 9-9 Cassette Handler Record Format 
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The control byte contains one of three values: 
o FC indicates the record is a full data record (128 bytes). 


o0 $FA indicates the record is a partially full data record; you 
Supplied fewer than 128 bytes to the record. This case can 
occur only in the record prior to the end-of-file. The number 
of user-supplied data bytes in the record is contained in the 
byte prior to the checksum. 


0 #FE indicates the record is an End-of file record: the data 
portion is all zeroes for an end-of-file record. 


The SIO routine generates and checks the checksum. It is part of the 
tape record, but it is not contained in the Handler’s record buffer 
CASBUF COSFDI. 

The processing of the speed-measurement bytes during cassette reading 
is discussed in Appendix L, D1-D7. 

File Structure 

The Cassette Handler writes a file to the cassette device with a file 
structure that is totally imposed by the Handler (soft format). A file 
consists of the following three elements: 

o A 20-second leader of mark tone. 


o Any number of data-record frames. 


o An end-of-file frame. 


The cassette-data record frames are formatted as shown below: 


frame = pre-record write tone (PRWT?), 
+ data record: 
+ post record gap (PRG) 


The nondata portions of a frame have characteristics that are 
dependent upon the write OPEN mode, i.e. continuous or 
start/stop. 


Stop/start PRWT 
Continuous PRWT 


3 seconds of mark tone. 
.25 second of mark tone. 


Stop/start PRG = up to 1 second of unknown tones. 
Continuous PRG = from O to n seconds of unknown tones, where 
mis dependent upon your program timing. 


The inter-record gap (IRG) between any two records consists of 
the PRG of the first record followed by the PRWT of the second 
record. 
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Printer Handler (P: } 


The Printer device is a write-only device with a Handler that 
supports the following CIO functions: 


OPEN 
CLOSE 
PUT CHARACTERS 


PUT RECORD 
GET STATUS 


The Printer Handler can produce the following error statuses: 
$8A-90 -- SIO error set (see Appendix C?}. 


The Printer Handler is one of the resident handlers. and 
therefore has a set of device vectors starting at location E430. 


CIO Function Descriptions 


The device-specific characteristics of the standard CIO functions 
are detailed below: 


OPEN 


The device name is P. The Handler ignores any device number and 
filename specification, if included. 


CLOSE 


The Handler writes any data remaining in its buffer to the 
printer device, with trailing blanks to fill out the line. 


PUT CHARACTERS and PUT RECORD 


The Handler accepts print data in the following format: 


7 O 
tot —+— 4-4-4 -4—-4-4 
H ATASCII H 
Se ee ee Se ee ee nS 


The only ATASCII control code of any significance to the Handler 
is the EOL character. The printer device ignores bit 7 of every 

data byte and prints a sub set of the remaining 128 codes. (see 

Appendix G for the printer character set). 


The Handler supports the following print option: 
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7 O 
5 santa dieaiaaienie tee sees chee dele eee 
AUX2 i print mode H 
5 a aieaiatenis sea ieee eae aieeiec ee 


Where: $4E (N) selects normal printing (40 characters per line). 
$53 (S) selects sideways printing (29 characters per line}. 
$57 (W) selects wide printing (not supported by printer 

device}. 


Any other value (including O00) is treated as a normal (N) 
print select, without producing an error status. 


GET STATUS 


The Handler obtains a 4-byte status from the printer 
controller and puts it in system location DVSTAT CO2EA]. The 
format of the status bytes is shown below: 


Salata shen aieee steele cake aieaie sei ieee 
i command stat. : DVSTAT + @G 
Sees aieeie aieeeie sie cies see eee al 
: AUX2 of prev. | + |j 
Sei dee Sheela eee siete ei eke 
H timeout { + 2 
Se ee ee ee ee oe oe oe 
{ Cunused } { + 3 
Se ee ee on a oo ore 


The command status contains the following status bits and 
condition indications: 


ott > an invalid command frame was received. 
ee ee an invalid data frame was received. 
bit 7: an intelligent controller (normally = OQ}. 


The next byte contains the AUX2 value from the previous operation. 


The timeout byte contains a controller provided maximum timeout 
value (in seconds}. 


Theory of Operation 


The ATARI S2O0CTM] 40-—Column Printer is a Lline-at-a-time printer rather 
than a character-at-a-time printer, so your data must be buffered by 
the Handler and sent to the device in records corresponding to one 
print Line (40 characters for normal, 29 characters for sideways). 
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The printer device does not attach any significance to the EOL 
character, so the Handler does the appropriate blank fill 
whenever it sees an EOL. 


Disk File Manager (D: }) 


The OS supports four unique File Management Subsystems at the 
time of this writing. Version IA is the original version. 

Version IB is a slightly modified version of IA and is the one 
described in this document. Most of this discussion applies as 
well to Version II. that handles a double-density diskette (720 
256-byte sectors}? in addition to the single-density diskette (720 
128-byte sectors). Version III has all new file/directory/map 
structures and can possibly contain changes to your interface 

as well. 


The File Management Subsystem includes a disk-bootable 
(RAM-resident) Disk File Manager (DFM) that maintains a 
collection of named files on diskettes. Up to 4 disk drives 

(Di: through D4:}) can be accessed, and up to 64 files per 
diskette can be accessed. The system diskettes supplied by ATARI 
allow a single disk drive (Di) and up to 3 OPEN files, but 

you can alter these numbers as described later in 

this section. 


The Disk File Manager supports the following CIO functions: 


OPEN FILE 

OPEN DIRECTORY 
CLOSE 

GET CHARACTERS 
GET RECORD 

PUT CHARACTERS 
PUT RECORD 

GET STATUS 


NOTE 
POINT 
LOCK 
UNLOCK 
DELETE 
RENAME 
FORMAT 
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The Disk File Manager can produce the following error statuses: 


@ $O3 -- Last data from file (EOF on next read). 
$88 -- end-of-file. 
$B8A-90 -- SIO error set (see Appendix C}. 


$AO -—--— Drive number specification error. 

$Ai -- No sector buffer available (too many open files). 
$A2 -- Disk full. 

$AS -- Fatal I/0 error in directory or bitmap. 

$A4 -- Internal file # mismatch (structural problem). 
$A5 -- File name specification error. 

$AG -- Point information in error. 

$A7 -- File locked to this operation. 

$AS -- Special command invalid. 

$A9 -- Directory full (64 files). 

GAA -- File not found. 

$AB -- Point invalid (file not OPENed for updafe?. 


CIO Function Descriptions 


The device-specific characteristics of the standard CIO functions 
ate detailed below: 


OPEN FILE 


The device name is D. Up to four disk drives can be accessed (Di 
through D4). The disk filename can be from i to 8 characters in 
length with an optional 1- to S-character extension. 


The OPEN FILE command supports the following options: 


tapos 
AUX i { iWIR! 
boat 


Where: W and R are the direction bits. 
WR = OO is invalid 
O1 indicates OPEN for read only. 
10 indicates OPEN for write only. 
11 indicates OPEN for read/write (update). 


A = 1 indicates appended output when W = 1. 


You may use these following valid AUX1 options: 
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OPEN Input (AUXI = $04) 


The indicated file is opened for input. Any wild-card characters 
are used to search for the first match. If the file is not found, 
an error status is returned, and no file will be opened. 


OPEN Output (AUX1 = $08) 


The indicated file is opened for output starting with the first 
byte of the file, if the file is not locked. Any wild-card 
characters are used to search for the first match. If the file 
already exists, the existing file will be deleted before opening 
the named file as a new file. If the file does not already exist, 
it will be created. 


A file opened for output will not appear in the directory until 
it has been closed. If an output file is not properly closed, 
some or ali of the sectors that were acquired for it can be lost 
until the disk is reformatted. 


A file that is opened for output can not be opened concurrently 
for any other access. 


OPEN Append (AUX1I = $09) 


The indicated file is opened for output starting with the byte 
after the last byte of the existing file (that must already 
exist), if the file is not locked. Any wild-card characters are 
used to search for the first match. 


If a file opened for append is not properly closed, the appended 
data will be lost. The existing file will remain unmodified and 
some or all of the sectors that were acquired for the appended 
portion can be lost until the diskette is reformatted. 


OPEN Update (AUX1 = $0C) 


The indicated file (that must already exist} will be opened for 
update provided it is not locked. Any wild-card characters are 
used to search for the first match. 


The GET. PUT, NOTE and POINT operations are all valid, and can be 
intermixed as desired. 


If a file opened for update is not properly closed, a sector’s 
worth of information can be lost to the file. A file opened for 
update can not be extended. 
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Device/Filename Specification 


The Handler expects to find a device/filename specification of 
the following form: 


Di<number>]: <filename><EOL> 


where: 
<number> ::= Li2iaia 
<filename> = C€<primaryo ll. C<extension>J]<terminator> 
<primary> ::= an uppercase alpha character followed by O to 7 


alphanumeric characters. If the primary name is 
less than 8 characters, it will be padded with 
blanks: if it is greater than & characters, the 
extra characters will be ignored. 


<extension> ::= Zero to 3 alphanumeric characters. If the 
extension name is missing or less than 3 
characters, it will be padded with blanks; if 
it is greater than 3 characters, the extra 
characters will be ignored. 


<terminator> ::= <EOL>i<blank> 


Figure 5-10 Device/Filename Syntax 


The following are all valid device/filenames for the diskette: 


Di: GAME. SRC 


D: MANUALG 
D: . WHY 
D3: FILE 


Filename Wildcarding 


The filename specification can be further generalized to include 
the use of the “wild-card" characters * and *. These wildcard 
characters allow portions of the primary and/or extension to be 
abbreviated as follows: 


The ? character in the specification allows any filename 
character at that position to produce a “match.“ For example, WH? 
will match files named WHO. WHY, WH4., etc., but not a file named 
WHAT. 
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Bi 


The * character causes the remainder of the primary or extension 
field in that it is used to be effectively padded with ? 
characters. For example, WH will match WHO, WHEN, WHATEVER, etc. 


Some valid uses of wild-card specifications are shown below: 


#. SRC Files having an extension of SRC. 

BASIC. # Files named BASIC with any extension. 

*. All files. 

He. 7 Files beginning with H and having a O or 1 


character extension. 


If wildcarding is used with an OPEN FILE command. the first file 
found (if any)? that meets the specification will be the one (and 
only one) opened. 


OPEN DIRECTORY 


The OPEN DIRECTORY command allows you read directory 

information for the selected filename(s}, using normal GET 
CHARACTERS or GET RECORD commands. The information read will be 
formatted as ATASCII records, suitable for printing: as shown 
below. Wildcarding can be used to obtain information for multiple 
files or the entire diskette. 


The OPEN DIRECTORY command uses the same CIO parameters as a standard 
OPEN FILE command: 


COMMAND BYTE = $03 
BUFFER ADDRESS = pointer to device/filename specification. 
AUX1 = $06 
After the directory is opened, a record will be returned to the 
caller for each file that matches the OPEN specification. The 


record, that contains only ATASCII characters, is formatted as 
shown below: 


1 
i .2:3 4 $.4 7-3 93 0 1-22.34 2-678 
++ — 4 — 4 — 4 — $4 4 Ht ta te tt tt 
istbi primary name {= ext tbicountie: 
$a ta et tt te te te ta to ttt 
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Where: s = # or ‘ ‘%, with # indicating file locked. 
= blank. 
primary name = left-yustified name with blank fill. 
ext = left-yjustified extension with blank fill. 
b = blank. 
count = number of sectors comprising the file. 
e = EOL ($98). 


or 
i 


After the last filename match record is returned, an additional 
record is returned. This record indicates the number of unused 


sectors available on the diskette. The format for this record is shown 
below: 


1 
(23 43 646769 012 34 3 6 7 
+ at tt ta tt tt tt 
‘count! FREE SECTOR Siei 
a a et a tt tat tt tt 


Where: count = the number of unused sectors on the diskette. 
e = EDL ($9B>. 


The EOF statuses ($03 and $88) are returned as in a normal data 
file when the last directory record is read. 


The opening of another diskette file while the directory read is 
open will cause subsequent directory reads to malfunction, so 
care must be taken to avoid this situation. 


CLOSE 


Upon closing a file read, the Handler releases all internal 
resources being used to support that file. 


Upon closing a file write, the Handler: 


Oo writes any residual data from its file buffer for that file 
to the diskette. 


o updates the directory and allocation map for the associated 
diskette. 


o releases all internal resources being utilized to support 
that file 


GET CHARACTERS and GET RECORD 


Characters are read from the diskette and passed to CIO as a raw 
data stream. None of the ATASCII control characters have any 
special significance. A status of $88 is returned if an attempt 
is made to read past the last byte of a file. 
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PUT CHARACTERS and PUT RECORD 


Characters are obtained from CIO and written to the diskette as a raw 
data stream. None of the ATASCII control characters have any special 


significance. 


GET STATUS 


The indicated file is checked and one of the following status 
byte values is returned in ICSTA and register Y: 


$O1-- File found and unlocked. 
$A7 -- File locked. 
FAA -- File not found. 


Special CIO Functions 


The DFM supports a number of SPECIAL commands, that are device 
specific. These are explained in the paragraphs that follow: 


NOTE (COMMAND BYTE = $25} 


This command returns to the caller the exact diskette location of 


the next byte to be read or written, in the variables shown 
below: 


ICAX3 = LSB of the diskette sector number. 
ICAX4 = MSB of the diskette sector number. 
ICAX5 = 


relative sector displacement to byte (0-124). 


POINT (COMMAND BYTE = $26) 


This command allows you to specify the exact diskette location of 
the next byte to be read or written. In order to use this commmand, 
the file must have been opened with the “update” option. 


ICAX3S = LSB of the diskette sector number. 
ICAX4 = MSB of the diskette sector number. 
ICAX5S = 


relative sector displacement to byte (0-124). 
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LOCK 


This command allows you to prevent write access to any 

number of named files. Locked files can not be deleted, renamed, 
nor opened for output unless they are first unlocked. Locking a 
file that is already locked is a valid operation. The Handler 
expects a device/filename specification: then all occurrences of 
the filename specified will be locked. using the wild-card rules. 


You set up these following IOCB parameters prior to 
calling CIO: 


COMMAND BYTE = $23 
BUFFER ADDRESS = pointer to device/filename specification. 


After a LOCK operation, the following IOCB parameter will have 
been altered: 


STATUS = result of LOCK operation: see Appendix B for a list 
of possible status codes. 


UNLOCK 


This command allows you to remove the lock status of any 

number of named files. Unlocking a file that is not locked is a 
Valid operation. The Handler expects a device/filename 
specificationi then all occurrences of the filename specified 
will be unlocked, using the wild-card rules. 


You set up these following IOCB parameters prior to 
calling CIO: 


COMMAND BYTE = $24 
BUFFER ADDRESS = pointer to device/filename specification. 


After an UNLOCK operation, the following IOCB parameter will have been 
altered: 


STATUS = result of UNLOCK operationi see Appendix B for a 
list of possible status codes. 


DELETE 


This command allows you to delete any number of unlocked 

named files from the directory of the selected diskette and to 
deallocate the diskette space used by the files involved. The 
Handler expects a device/filename specification; then all 
occurences of the filename specified will be deleted, using the 
wild-card rules. 
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You set up these following IOCB parameters prior to 
calling CIO: 


COMMAND BYTE = $21 
BUFFER ADDRESS = pointer to device/filename specification. 


After a DELETE operation, the following IOCB parameter will have 
been altered: 


STATUS = result of DELETE operationi see Appendix B for a list of 
possible status codes. 


RENAME 


This command allows you to change the filenames of any 
number of unlocked files on a single diskette. The Handler 
expects to find a device/filename specification that follows: 


<device spec>:<filename spec>,< filename spec><EOL> 


All occurrences of the first filename will be replaced with the 
second filename, using the wild-card rules. No protection is 
provided against forming duplicate names. Once formed, duplicate 
names cannot be separately renamed or deleted: however, an OPEN 
FILE command will always select the first file found that matches 
the filename specification, so that file will always be 
accessible. The RENAME command does not alter the content of the 
files involved, merely the name in the directory. 


Examples of some valid RENAME name specifications are shown 
below: 


Di: +. SRC, #. TXT 
D: TEMP, FDATA 
D2: F#, *. OLD 


You set up these following IOCB parameters prior fo 
calling CIO: 


COMMAND BYTE = $20 
BUFFER ADDRESS = pointer to device/filename specification. 


After a RENAME operation, the following IOCB parameter will have 
been altered: 


STATUS = result of RENAME operationi see Appendix GB for a 
list of possible status codes. 
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FORMAT 


Soft-sector diskettes must be formatted before they can store 
data. The FORMAT command allows you to physically format a 
diskette. The physical formatting process writes a new copy of 
every sector on the soft-sectored diskette, with the data portion 
of each sector containing all zeros. The FORMAT process creates 
an “empty“ non system diskette. When the formatting process is 
complete, the FMS creates an initial Volume Table of Contents 
(VTOC} and an initial File Directory. The boot sector (#1) is 
permanently reserved as part of this process. 


You set up these following IOCB parameters prior to 
calling CIO: 


COMMAND BYTE = $FE 
BUFFER ADDRESS = pointer to device specification. 


After a FORMAT operation, the following IOCB parameter will have 
been altered: 


STATUS = result of FORMAT operation: see Appendix B for a 
list of possible status codes. 


To create a system diskette, a copy of the boot file must then be 
written to sectors #2-n. This 185 accomplished by writing the file 
named DOS.SYS. This is a name that is recognized by the FMS even 
though it is not in the directory initially. 


Theory of Operation 


The resident OS initiates the disk-boot process (see Section 10). 
The OS reads diskette sector #1 to memory and then transfers 
control to the “boot continuation address" (boot address + 6). 
The boot-continuation program contained in sector #1 then 
continues to load the remainder of the File Management Subsystem 
to memory using additional information contained in sector #1. 
The File Management Subsystem loaded, will contain a Disk File 
Manager ,and optionally, a Disk Utilities (BOS) package. 


When the boot process is complete, the Disk File Manager will 
allocate additional RAM for the creation of sector buffers. 


Sector buffers are allocated based upon information in the boot 
Tecord as shown below: 


Byte 9 = maximum number of open files: one buffer per (the 
maximum value is 8). 


Byte 10 = drive select bitsi one buffer per (1-4 only). 
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The Disk File Manager will then insert the name D and the Handler 
vector table address in the device table. 


NOTE: There is a discrepancy between the Disk File Manager ’s 
numbering of diskette sectors (0-719) and the disk controller’s 
numbering of diskette sectors (1-720); as a result, only sectors 
i- 7i? are used by the Disk File Manager. 


The Disk File Manager uses the Disk Handler to perform all 
diskette reads and writes; the DFM’s function is to support and 
maintain the directory/file/bitmap structures as described in the 
following pages: 


OPERATING SYSTEM CO146555 -- Section 5 
88 


FMS Diskette Utilization 


The map below shows the diskette sector utilization for a 
standard 720 sector diskette. 


+ + 
: BOOT record i Sector 1 

$e ee + 

i FMS BOOT ‘ Sector 2 andy 

= file = H 

H DOS. SYS t Sector n +—- Note 1 
Hp ee + : 

H User H Sector nti —-+ 

= File c= 

{ Area H Sector 3S? (%$167) 
ee res + 

H VTOC (note 2) i Sector 360 ($168) 
pm a + 

H File t Sector 361 (#1469) 
= Directory = 

{ t Sector 348 (%170) 
ome ee + 

H User H 

= File = 

H Area H Sector 71i? (#$2CF) 
$e + 

{ unused ‘ Sector 720 ($2D0> 
$a + 


Figure S-il File Management Subsystem Diskette Sector Utilization 
Map 


NOTE i - If the diskette is not a system diskette, then your 

File Area starts at sector 2 and no space is reserved for the FMS 
BOOT file. However, “DOS" (BOS. SYS and DUP. SYS} may still be 
written to a diskette that has already used sectors “2-N. “ 


NOTE 2 -- VTOC stands for Volume Table of Contents. 
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FMS Boot Record Format 


The FMS BOOT record (sector #1) is a special case of diskette-booted 
software (see Section 10). The format for the FMS BOOT record is 
shown below: 


code for second: 


phase of boot : 


+ ——— + 

t boot flag = O Byte © 

$——— — — + 

i # sectors = 1 { 1 

$ + 

H boot address { 2 

+ + 

H = 0700 H 

$——— + 

{ init address { a 

+ + 

$e + 

H JMP = $46 { & 

+ * 

{ boot read H 

+ continuation + 

{ address H 

$e + —--—+ 

i max files = 3 i H 9 Note i 
paca ee + 

: drive bits = 1 ¢ H 10 Note 2 
poe + t 

it alloc direc = O H 1i1 Note 3 
pe + 

t boot image end | H 

+ + ‘ FMS 
i address + i H fe re ene arene configuration 
ane a= Seige ga + data 
| boot flag <> O | ‘ 14 Note 4 
$e ee 4 

i sector count { ‘ 15 Note 5 
+—--------------- + 

{ DOS. SYS { ‘ 

+ starting + 

i sector number H H 

+—— — + —-—-—+ 


Figure 5-12 File Management Subsystem Boot Record Format 
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NOTE i 


NOTE 2 


NOTE 3 


NOTE 4 


NOTE 5S 


Byte 9? specifies the maximum number of concurrently open 
files to be supported. This value can range from 1 to 8. 


Byte 10 specifies the specific disk drive numbers fo be 
supported using a bit encoding scheme as shown below: 


7&5 432i 0 
+ — $f — HH 

H t4iGi2ii! where a il indicates a selected drive. 
$= — 4  — 4 HH 


Byte i1 specifies the buffer allocation direction, this 
byte should equal O. 


Byte 14 must be nonzero for the second phase of the boot 
process to initiate. This flag indicates that the file 
DOS. SYS has been written to the diskette. 


This byte is assigned as being the sector count for the 
DOS. SYS file. It is actually an unused byte. 
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Boot Process Memory Map 


The diagram below shows how the boot sector (part of file 
DOS. SYS) and following sectors are loaded to memory as part of 
the boot process. 


$a ee ee + Memory address 0700 
i data from boot | H 

= sector read by = H 

i resident OS H O77C 
+——-———— -— + 

i: data from rest i 6077D 
: of DOS. SYS H { 

i read by the H H 

= program in the = { 

it boot sector. H H 

S slaestoesteniaatonstentaianatetantententantentetan + end of boot @ 


Figure 5-13 File Management Subsystem Boot Process Memory Map 
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Volume Table of Contents 


@ The format for the FMS volume table of contents (VTOC, sector 
360) is shown in the diagram below: 


een oe 
i directory type | Byte QO Note 1 
De + 
i maximum Cio? 1 Note 2 
+ sector # + 
: = O2C5 2% 8 ae 
Fa a + 
i number of (lo) | 3 Note 3 
+ sectors » 
i available (hid ; 
pe ae ee + 
+ + 
H t 10 
= volume bit map = 
po eee + 
+ 


{ 
| 
& sf ee ee ee 


Figure 5-14 File Management Subsystem Volume Table of Contents 


The volume bit map organization location follows: 


7 0 
topo tee —t—t— tt 
f (12345 6 7: Byte 10 of VTOC 
+t tet —4—t— 4-4-4 
io: s= ii 
} 99 


+—+—t—+—4+—-4+—-4+-4—-4+ 
Figure S-iS File Management Subsystem Volume Bit Map 


At each map bit position, a O indicates the corresponding sector 
is in use and a i indicates that the sector is available. 


NOTE i - The directory type byte must equal QO. 
NOTE 2 -—- The maximum sector number is not used because it 15 


incorrectly set to 7O9 decimal. The true maximum sector 
number is actually 719 for the DFM. 
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NOTE 3 - The number of sectors available is initially set to 709 
after a diskette is freshly formatted; this number is 
adjusted as files are created and deleted to show the 
number of sectors available. The sectors that are 
initially reserved are 1 and 360-368. 


File Directory Format 


The FMS reserves eight sectors (361-368) for a file directory. 
Fach sector containing directory information for up to eight 
files, thus providing for a maximum of 64 files for any volume. 
The format of a single 16-byte file entry is shown below: 


me + 
H flag byte { Byte O 
pe ee ee + 

{ sector (ie) -i 1 
+ count + 

i (hit -3 

+—-—— — + 

i starting (lo) | a 
+ sector + 

: number (33-3 

$a + 

i (43.3 S 
+ + 

t (2) } 

+ + 

H (3) i 

+ + 

H file (4) | 

+ + 

‘ name =. > eae 

+ + 

i primary (6) ¢ 

+ + 

‘ €7} 3 

+ + 

H (8) | 

$e + 

t file = 2 ap i3 
+ + 

H name 7 2 ee 

+ + 

} extension (3) | 

$a + 


Figure 9-16 File Directory Format 


Where the flag byte has the following bits assigned: 
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bit 7 = 1 if the file has been deleted. 
bit 6 = 1 if the file is in use. 

bit 5 = 1 if the file is locked. 

bit O = 1 if OPEN output. 


The flag byte can take on the following values: 


$00 = entry not yet used (no file). 

$40 = entry in use (normal CLOSEd file}. 
$41 = entry in use (OPEN output file). 

$640 = entry in use (locked file}. 

$80 = entry available (prior file deleted}. 


Sector count is the number of sectors comprising the file. 


FMS File Sector Format 


The format of a sector in your data file is shown below: 


7 0 
Sots see siects decks eaten ease 

H data i +0 
+--+ —F—4+—-4F—-4-—4-4 

i file # thi : +125 
Sole aes eee ee ee ee + 
‘forward pointer: +126 
+--+ +--+ —-4+—-4+- 4-4 

(Sit byte count : +127 
+—t—+— + -4F—-4$—-4-4-4+ 


Figure 5-17 File Management Subsystem File Sector Format 


The FMS uses the file #€ to verify file integrity. The file # 

is a redundant piece of information. The file number field 
contains the value of the directory position of that file. If a 
mismatch occurs between the file’s directory position, and the 
file number as contained in each sector, then the DFM will 
generate the error $A4. 


The forward pointer field contains the 10-bit value for the 
diskette sector number of the next sector of the file. The 
pointer equals zero for the last sector of a file. 


The S&S bit indicates whether or not the sector is a “short sector" 
(a sector containing fewer than 125 data bytes). S is equal to 
1 when the sector is short. 
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The byte-count field contains the number of data bytes in the 
sector. 


Non-CIQ 1/0 


Some portions of the I/0 subsystem are accessed independently of 
the Central I[/0 Utility (CIO}; this section discusses those 
areas. 


Resident Device Handler Vectors 


All of the OS ROM resident device handlers can be accessed via 
sets of vectors that are part of the OS ROM. These vectors 
increase the speed of I/O operations that utilize fixed device 
assignments, such as output to the Display Handler. For each 
resident Handler there is a set of vectors ordered as shown 
below: 


Pio ee 7 
=~ OPEN ona +O 
+ -- -  e + 
+— CLOSE =+ +2 
$e ee + 
+—- GET BYTE —+ +4 
+-- + 
jn: FUT BYTE => +& 
rs + 
+- GET STATUS -+ +8 
Fe -- eee  e + 
+ SPECIAL sae +10 
+ + 
+ JMP an +12 
+ INIT —+ 
+——-—-———- + 
+ SPARE op 
+= BYTE + 
$———— + 

Figure 5-18 Resident Device Handler Vectors 


See Section 3 for a detailed description of the data interface 
for each of these Handler entry points. 


Each of the vectors contains the address (lo,hi} of the Handler 
entry point minus 1. A technique similar to the one shown below 
is Tequired to access the desired routines: 
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VTBASE=$E400 i; BASE OF VECTOR TABLE. 


LDX # x x i; OFFSET TO DESIRED ROUTINE. 


LDA data 
JSR GOVEC i SEND BATA TO ROUTINE. 
LDX #y y i OFFSET TO DIFFERENT ROUTINE. 
JSR GOVEC i GET BATA FROM ROUTINE. 
STA data 

GOVEC TAY i SAVE REGISTER A. 
LBA VTBASE+1, X i ADDRESS MSB TO STACK. 
PHA 
LBA VTBASE. X i ADDRESS LSB TO STACK. 
PHA 
TYA i RESTORE REGISTER A. 
RTS i; JUMP TO ROUTINE. 


The JMP INIT slot in each set of vectors jumps to the Handler 
initialization entry (not minus 1). 


The base address of the vector set for each of the resident 
handlers is shown below: 


Screen Editor (E: } E400. 
Display Handler (S: } E410. 
Keyboard Handler (K: ?) E420. 
Printer Handler (P: > E430. 
Cassette Handler (C: ) E440. 


The resident diskette Handler is not CIlO-compatible., so its 
interface does not use a vector set. 


Resident Diskette Handler 


The resident Diskette Handler (not to be confused with the Disk 
File Manager) is responsible for all physical accesses to the 
diskette. The unit of data transfer for this Handler is a single 
diskette sector containing 128 data bytes. 


Communication between you and the Diskette Handler is 

effected using the system’s Device Control Block (DCB), that is 

also used for Handler/SIO communication (see Section 9). The DCB 
is 12 bytes long. Some bytes are user-alterable and some are for 
use by the Diskette Handler and/or the Serial I/0 Utility (S10). 
You supply the required DCB parameters and then do a JSR 

DSKINY CE453]. 
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Each of the DCB bytes will now be described, and the 
system-equate file name for each will be given. 

SERIAL BUS ID -- BDEVIC [0300] 

The Diskette Handler sets up this byte to contain the Serial Bus ID 
for the drive to be accessed. It is not user-alterable. 

DEVICE NUMBER -- DUNIT (03011 

You set up this byte to contain the disk drive number to be 
accessed (i -— 4}. 

COMMAND BYTE -—-- DCOMND [0302] 

You set up this byte to contain the disk device command to 

be performed. 

STATUS BYTE -~ DSTATS [£0303] 

This byte contains the status of the command upon return to the 
caller. See Appendix C for a list of the possible status codes. 
BUFFER ADDRESS -- DBUFLO [0304] and DBUFHI [0305] 

This 2-byte pointer contains the address of the source or 
destination of the diskette sector data. You need not supply 

an address for the disk status command. The Disk Handler will 
obtain the status and insert the address of the status buffer 
into this field. 

DISK TIMEOUT VALUE -- DTIMLO [0306] 

The Handler supplies this timeout value (in whole seconds) for 
use by SIQ. 

BYTE COUNT -- DBYTLO [0308] and DBYTHI (0309) 

This 2-byte counter indicates the number of bytes transferred to 
or from the disk as a result of the most recent command, and 15 
set up by the Handler. 

SECTOR NUMBER -- DAUX1 COS3OA] and DAUX2 COSOB] 


This 2@-byte number specifies the diskette sector number (1 - 720) 
to read or write. DAUX1 contains the least significant byte, and 
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DAUX2 contains the most significant byte. 


Diskette Handler Commands 

There are five commands supported by the Diskette Handler: 

GET SECTOR (PUT SECTOR --### not supported by current handler ###) 

PUT SECTOR WITH VERIFY 

STATUS REQUEST 

FORMAT DISK 
GET SECTOR (Command byte = $52) 
The Handler reads the specified sector to your buffer and returns the 
operation status. You set the following DCB parameters prior to 
calling the Diskette Handler: 

COMMAND BYTE = $52. 

DEVICE NUMBER = disk drive number (1-4}. 

BUFFER ADDRESS = pointer to your 128-byte buffer. 


SECTOR NUMBER = sector number to read. 


Upon return from the sector, several of the other DCB parameters 
will have been altered. The STATUS BYTE will be the only 
parameter of interest to you, however. 


PUT SECTOR (Command byte = $50} 


##% Not supported by current Handler #++# 
(But can be accessed through SIO directly. > 


The Handler writes the specified sector from your buffer and returns 
the operation status. You set the following DCB parameters prior to 
calling the Diskette Handler: 

COMMAND BYTE = $50. 

DEVICE NUMBER = disk drive number (1-4). 

BUFFER ADDRESS = pointer to your 128 byte buffer. 

SECTOR NUMBER = sector number to write. 
Upon return from the operation, several of the other DCB parameters 


Will have been altered. The STATUS BYTE will be the only one of 
S interest you, however. 
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PUT SECTOR WITH VERIFY (Command Byte = $57) 


The Handler writes the specified sector from your buffer 

and returns the operation status. This command differs from PUT 
SECTOR in that the diskette controller reads the sector data after 
writing to verify the write operation. Aside from the COMMAND 

BYTE value, the calling sequence is identical to PUT SECTOR. 


STATUS REQUEST (Command byte = $53) 


The Handler obtains a 4-byte status from the diskette controller and 
puts if in system location DVSTAT CO2EA). The operation status 
format is shown below: 


7 0 
+—+—4+—4—-4+—-4-—4—-4-—4+ 
i command stat. | DVSTAT + O 
oe ee ee oe 
i hardware stat. i 4 
+—+—+—4+—4+—4—-4—4—-4+ 
H timeout H + 2 
Se ee ee ee oe 
{ (unused >} { = 3 


| leas ani aeeeinaieen aie ac aieaia aed 
Figure 5-19. DBVSTAT 40-Byte Operation Status Format 


The command status contains the following status bits: 


Bit O = i indicates an invalid command frame was received. 
Bit 1 = 1 indicates an invalid data frame was received. 
Bit 2 = 1 indicates that a PUT operation was unsuccessful. 
Bit 3 = 1 indicates that the diskette is write protected. 
Bit 4 = 1 indicates active/standby. 


The hardware status byte contains the status register of the 
INS1771-1 Floppy Diskette Controller chip used in the diskette 
controller. See the documentation for that chip to obtain 
information relating to the meaning of each bit in the byte. 


The timeout byte contains a controller-provided maximum timeout 
value (in seconds) to be used by the Handler. 


You set the following DCB parameters prior to calling 
the Diskette Handler: 


COMMAND BYTE = $53. 
DEVICE NUMBER = disk drive number (1-4). 


Upon return from the operation, several of the other DCB parameters 
will have been altered. The STATUS BYTE will be the only one of 
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interest to you. however. 


FORMAT DISK (Command Byte = $21)? 


The Handler commands the diskette controller to format the entire 
diskette and then to verify it. All bad sector numbers (up to a 
maximum of 63) are returned and put in the supplied buffer, 
followed by two bytes of all 1’S (S$FFFF). You set up the 
following DCB parameters prior to calling the Diskette Handler: 


COMMAND BYTE = $21. 
DEVICE NUMBER = disk drive number (1-4}. 
BUFFER ADDRESS = pointer to your 128-byte buffer. 
Upon return, you might be interested in the following DCB parameters: 
STATUS BYTE = status of operation. 


BYTE COUNT = number of bytes of bad sector information in 
your buffer, not including the S$FFFF terminator. If there 
are no bad sectors, the count will equal zero. 


Serial Bus I/0 


Input/Output to devices other than the keyboard, the screen, and 
the ATARI Computer controller port devices, must utilize the 
Serial I/0 bus. This bus contains data, control, and clock lines 
to be used to allow the computer to communicate with external 
devices on this “daisychained" bus. Every device on the bus has 
a unique identifier and will respond only when directly 
addressed. 


The resident system provides a Serial 1/0 Utility (SIO), that 
provides a standardized high-level program interface to the bus. 
SIO is utilized by the resident Diskette, Printer, and Cassette 
handlers, and is intended to be used by nonresident handlers (see 
Section 9}. or by applications. as well. For a detailed 
description of the program/SIO interface and for a detailed bus 
specification refer to Section 9. 
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& INTERRUPT PROCESSING 


Section 6 describes system actions for the various interrupt 
causing events, defines the many RAM vectors and provides 
recommended procedures for dealing with interrupts. 


The 6502 microcomputer processes three general interrupt types: 
chip-reset, nonmaskable interrupts (NMI) and maskable interrupts 
(IRG>}. The IRG@ interrupt type can be enabled and disabled using 
the 6502 CLI and SEI instructions. The NMI type cannot be 
disabled at the processor leveli but the NMI interrupts other 
than CSYSTEM. RESET] key can be disabled at the ANTIC chip. 


The system events that can cause interrupts are listed below: 
chip-reset - power-up 


NMI —- Display list interrupt (unused by OS) 
vertical-blank (50/60 Hz} 
CSYSTEM. RESET] key 


IRQ - Serial bus output ready 
Serial bus output complete 
Serial bus input ready 
Serial bus proceed line (unused by system) 
Serial bus interrupt line (unused by system) 
POKEY timers 1, 2 and 4 
Keyboard key 
CBREAK] key 
6502 BRK instruction (unused by OS) 


Figure 6-1 List of System-Interrupt Events 
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The chip-reset interrupt is vectored via location FFFC to E477, 
where a JMP vector to the power-up routine is located. All NMI 
interrupts are vectored via location FFFA to the NMI interrupt 
service routine at E7B4, and all IRQ interrupts are vectored 
Via location FFFE to the IR@ interrupt service routine at EOFS: 
at that point the cause of the interrupt must be determined by 
a series of tests. For some of the events there are built in 
monitor actions and for other events the corresponding 
interrupts are disabled or ignored. The system provides RAM 
vectors so that you can intercept interrupts when 

necessary. 


CHIP-RESET 


The OS generates chip-reset in response to a power-up condition. 
The system is completely initialized (see Section 7). 


NONMASKABLE INTERRUPTS 


When an NMI interrupt occurs, control is transferred through 

the ROM vector directly to the system NMI interrupt service 
routine. A cause for the interrupt is determined by examining 
hardware register NMIST CD40F]. The NMI makes a jump through the 
global RAM vector VDSLST (CO200] if a display list interrupt is 
pending. The OS does not use display list interrupts, so VDSLST 
is initialized to point to an RTI instruction, and you must not 
change it before VDSLST generates a display interrupt. 


If the interrupt is not a display-list interrupt, then a test is 
made to see if it is a CSYSTEM. RESET] key interrupt. If so, then a 
jump is made to the system reset initialization routine (see Section 
7 for details of system reset initialization}. 


If the interrupt is neither a display list interrupt nor a 
CSYSTEM. RESET] key interrupt; then it is assumed to be a 
vertical-blank (VBLANK) interrupt, and the following actions 
occur: 

Registers A,X and Y are pushed to the stack. 

The interrupt request is cleared (NMIRES (CD40F]>. 

A sump is made through the “immediate" vertical-blank global 


RAM vector VVBLKI CO222] that normally points to the Stage 1 
VBLANK processor. 


@ The following actions occur assuming that you have not changed VVBLKI. 
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The stage i VBLANK processor is executed. 


The OS tests to see if a critical code section has been 
interrupted. If so; then all registers are restored, and an 
RTI instruction returns from the interrupt to the critical 
section. A critical section is determined by examining the 
CRITIC flag COO42], and the processor I bit. If either are 
set, then the interrupted section is assumed to be critical. 


If the interrupt was not from a critical section, then the 
stage 2 VBLANK processor is executed. 


The OS then jumps through the “deferred” vertical-blank 
global RAM vector VBLKD (0224], that normally points to the 
VBLANK exit routine. 


The following actions occur assuming that you have not changed VVBLKD. 
o The 6502 A.X and Y registers are restored. 


o An RTI instruction is executed. 


NOTE: You can alter the deferred and immediate 

VBLANK RAM vectors, but still enable normal system processes; or 
restore original vectors without having to save them. The 
instruction at E4SF is a JMP to the stage 1 VBLANK processori the 
address at ££460,2] is the value normally found in VVBLKI. The 
instruction at E462 is a JMP to the VBLANK exit routine; the 
address at ££463,2] is the value normally found in VVBLKD. These 
ROM vectors to stage i VBLANK processor and to the VBLANK exit 
routine will accomplish your goal. 


NOTE: Every VBLANK interrupt jumps through vector VVBLKI. Only 
VBLANK interrupts from noncritical code sections jump through 
vector VVBLKD. 


Stage 1 VBLANK Process 


The following stage i VBLANK processing is performed at every 
VBLANK interrupt: 


The stage i VBLANK process increments the 3-byte frame 
counter RTCLOK (0012-0014]; RTCLOK+0O is the MSB and RTCLOK+2 
is the LSB. This counter wraps to zero when it overflows 
(every 77 hours or so}, and continues counting. 


The Attract mode variables are processed (sea Appendix L. 
B10-12}. 


The stage i VBLANK process decrements the System Timer 1 
CDOTMVi (£0218,21] if it is nonzero; if the timer goes from 
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monzero to zero then an indirect JSR is performed via CDTMAI 
£0226, 2]. 


Stage 2 VBLANK Process 


The stage 2 VBLANK processing performs the following for those 
VBLANK interrupts that do not interrupt critical sections: 


The stage 2 VBLANK process clears the 6502 processor I bit. 
This enables the IRG interrupts. 


The stage 2 VBLANK process updates various hardware 


registers with data from the OS data base, 


as shown below: 


Data Base Hardware Reason for Update 
Item Register 

SDLSTH £0231] DLISTH €D403] Display list start 
SDLSTL C0230] DLISTL €D402] 

SDMCTL (CO22F] DMACTL CD400] 

CHBAS ([O02F4] CHBASE [D409] 

CHACT (02F3] CHACTL [D401] 

GPRIOR CO26F ] PRIOR fCDOiB] 

COLORO £02C4] COLPFO CDOI46] Attract mode. 
COLORI (CO2C5] COLPF1 [CDO1i73 

COLOR2 £02C6] COLPF2 (CDOiB) 

COLORS (02C7] COLPFS (CDOiI9] 

COLOR4 (02C8) COLBA {CDOiA] 

PCOLRO (02CO0] COLPMO [CDOi2) 

PCOLR1I (02C1] COLPM1 CDO1i3] 

PCOLR2 CO2C2] COLPM2 (D014) 

PCOLRS £02C3] COLPMS [DOiS] 

Constant = 8 CONSOL (CDOIF] Console speaker off. 


The stage 2 VBLANK process decrements the System Timer 2 
CBIMV2 CO21A, 2] if it is nonzero; if the timer goes from 
nonzero to zero, then an indirect JSR is performed 
through CDTMA2 (£0228, 2]. 


The stage 2 VBLAMK process decrements System Timers 3. 4 and 
> if they are nonzeroi the corresponding flags are set to 
zero for each timer that changes from nonzero to zero. 
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Timer Timer Value Timer Flag 
3 CDIMVS CO21C, 2] 
es CDTMV4 CO2I1E, 2] 


2 CDTIMVS (£0220, 2] 


CDTMFS CO22A, 1] 
CDIMF4 (O022C, 1] 
CDIMFS CO22E, 1] 


A character is read from the POKEY keyboard register and 
stored in CH CO2FC], if auto repeat is active. 


The stage 2 VBLANK process decrements the keyboard debounce 
counter if it is not equal to zero, and if no key is 
pressed. 


The stage 2 VBLANK process processes the keyboard auto 
repeat (see Appendix L, E®B>. 


The stage 2 VBLANK process reads game controller data from 


the hardware to the RAM data base, 


as shown below: 


Hardware Data Base Function 
Register Item 
PORTA [CD30O] STICKO £0278] Joysticks and 
STICK1 C0279] 
PTRIGO (027C] Paddle Controllers 
PTRIGI (CG27D] 
PTRIG2 (C027E] 
PTRIGS (CO27F] 
PORTB fD301i1] STICK2 CO27A] 
STICKS C027B] 
PTRIG4 [0280] 
PTRIGS C0281] 
PTRIG6& [0282] 
PTRIG7 C0283] 
POT G {CD200) PADDLO [0270] Paddle Controllers 
POT i fCDB2013 PADDL1 [0271] 
POT 2 f{DB202] PADDL2 [0272] 
POT 3 fD203] PADDL3 [0273] 
POT 4 [{B204] PADDL4 [£0274] 
POT 5S {CbB205) PADDLS (0275) 
POT & {fDB206] PADDL6& [0276] 
POT 7 {£D2073 PABDL7 [02771] 
TRIGO fCBOO1] STRIGO [0284] Joystick triggers. 
TRIGi (CDOO?2) STRIGiI (C0285) 
TRIGS CBOOS) STRIG2 C0286] 
TRIGS fCDO04] STRIGS £0287] 
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MASKABLE INTERRUPTS 


An IRG@ interrupt causes control to be transferred through the 

immediate IRG global RAM vector VIMIRG@ CO216]. Ordinarily this 
vector points to the system IR@ Handler. The Handler performs 

these following actions: 


The IRG@ Handler determines a cause for the interrupt by 

examining the IRGST CD20CE] register and the PIA status 

registers PACTL C€D3O02] and PBCTL [D303]. The interrupt status bit 
is cleared when it is found. One interrupt event is cleared and 
processed for each interrupt-service entry. If multiple IRGs are 
pending, then a separate interrupt will be generated for each 
pending IRG, until all are serviced. 


The system IRG@ interrupt service routine deals with each of the 
possible IR@ causing events, in the following ways: 


Oo The 6502 A register is pushed to the stack. 


3) If the interrupt is due to serial I/O bus output ready, 
then clear the interrupt and jump through global RAM 
vector VSEROR ([O20C]. 


2) If the interrupt is due to serial I/O bus input ready, 
fhen clear the interrupt and jump through global RAM 
vector VSERIN (CO2O0A]. 


3) If the interrupt is due to serial I/O bus output 
complete, then clear the interrupt and jump through 
global RAM vector VSEROC CO2OE]. 


o If the interrupt is due to POKEY timer #1, then clear the 
interrupt and jump through global RAM vector VTIMR1I [£0210]. 


3) If the interrupt is due to POKEY timer #2, then clear the 
interrupt and jump through global RAM vector VTIMR2 (CO212]. 


9) If the interrupt is due to POKEY timer #4, then clear the 
interrupt. The service routine contains a bug, and falls 
into the following test. 


3) If pressing a keyboard key caused the interrupt (other 
than CBREAK], CSTARTIJ., COPTION]., or CSELECTI}; then clear the 
interrupt and jump through global RAM vector VKEYBD (CO208]. 


Oo If pressing the CBREAK] key caused the interrupti then 
clear the interrupt. Set the BREAK flag BRAKKEY COO11] to 
zero, proceed to clear the following: 


Start/stop flag SSFLAG [CO2FF] 
Cursor inhibit flag CRSINH [CO2FO} 
Attract mode flag ATRACT ([COO4D] 
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Return from the interrupt after restoring the 4502 4 
register from the stack. 


a) If the interrupt is due to the serial I/0 bus proceed line; 
then clear the interrupt, and jump through global RAM vector 
VPRCED £0202]. 


a) If the interrupt is due to the serial 1/0 bus interrupt 
line, then clear the interrupt and jump through global RAM 
vector VINTER [C0204]. 


o If the interrupt is due to a 6502 BRK instruction, then jump 
through global RAM vector VBREAK [C0204]. 


o If none of the above, restore the 65602 A register and return 
from the interrupt (RTI). 


INTERRUPT INITIALIZATION 


The interrupt subsystem completely reinitializes itself whenever 
the system is powered up or the (SYSTEM. RESET] key is pressed. 
The OS clears the hardware registers, and sets the interrupt 
global RAM vectors to the following configurations: 


Vector Type Function 

VDSLST £0200] NMI RTI --— ignore interrupt. 

VVBLKI (CO222] = System stage i VBLANK. 

CDTMAi [0226] , SIO timeout timer. 

CDTMA2 (0228) ? No system function. 

VVBLKD £0224) "5 System return from interrupt. 

VIMIRG@ (0216) IRQ System IRG@ processor. 

VSEROR [020C] " Sito. 

VSERIN [CO20A] ° Siod. 

VSEROC (C20E) _ Siod. 

VTIMRi £60210) ” PLA, RTI -- ignore interrupt. 

VTIMR2 CO2i2) - PLA, RTI -- ignore interrupt. 

VTIMR4 £0214] “3 H##H# doesn’t matter ##+ 

VKAEYBD [0208] . System keyboard 

interrupt handler. 

VPRCED (0202) - PLA,RTI -- ignore interrupt. 

VINTER CO204} . PLA, RTI -- ignore interrupt. 

VBREAK [0206] BRA PLA, RTI -- ignore interrupt. 
Figure 6-2 Interrupt RAM Vector Initialization 
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System initialization sets the interrupt enable status 
as follouws: 


NMI VBLANK enabled, display list disabled. 


IRG [BREAK] key and data key 


disabled. 


interrupts enabled, all others 


SYSTEM TIMERS 


The OS contains five general purpose software timers, plus an 
OS-supported frame counter. The timers are 2 bytes in length 
(lo, hi} and the frame counter RTICLOK (COO12] is three bytes in 
length (hi.mid, lo}. The timers count downward from any 
nonzero value to zero. Upon reaching zero, they either clear 
an associated flag, or JSR through a RAM vector. The frame 
counter counts upward, wrapping to zero when it overflows. 


The following table shows the timers and the frame counter 
characteristics: 


Timer Name Flag/Vector Use 
CDITMV1 €O21i8] CDTMAI [0226] 2-byte vector -- SIO timeout. 
CDIMV2 CO21A] CDTMA2 C0228] 2-byte vector 
CDIMV3 €021C] CDITMFS CO22A] i-byte flag 
CDIMV4 CO2iE] CDTMF4 CO22C] i-byte flag 
CDIMVS (0220) CDTMFS CO22E] i-byte flag 
# RTCLOK (COOi2] S-byte frame counter. 


* These two timers are maintained as part of every VBLANK 
interrupt (stage 1 process). The other timers are subject to 
the critical section test (stage-2 process}, that can defer 
their updating to a later VBLANK interrupt. 


USAGE NOTES 


This subsection describes the techniques you need to know in 
order to utilize interrupts in conjunction with the operating 
system. 
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POKEY Interrupt Mask 


ANTIC (display-list and vertical-blank) and PIA (interrupt and 
proceed lines} interrupts can be masked directly (see the 
Hardware Manual}. However, eight bits of a single byte IRGEN 
[D20E] mask the POKEY interrupts (CBREAK] key. data key, 
serial input ready, serial output ready, serial output done 
and timers i.2 and 4}. 


IRGEN is a write-only register. Thus, we must maintain a 
current value of that register in RAM in order to update 
individual mask bits selectively, while not changing other bits. 
The name of the variable used is POKMSK COO10]., and it is used 
as shown in the examples below: 


; EXAMPLE OF INTERRUPT ENABLE 


SE I i TO AVOID CONFLICT WITH IRG ... 
LDA POKMSK i ... PROCESSOR WHICH ALTERS VAR. 
ORA #$ x x ; ENABLE BIT(S). 

STA POKMSK 

STA IRGEN i TO HARDWARE REG TOO. 

CLI 


i EXAMPLE OF INTERRUPT DISABLE 


SETI i TO AVOID CONFLICT WITH IRG ... 
LDA POKMSK i; ... PROCESSOR WHICH ALTERS VAR. 
AND #$FF-xx i DISABLE BIT(S). 

STA POKMSK 

STA IRQGEN i TO HARDWARE REGISTER TOO. 

CLI 


Figure 6-3 POKEY Interrupt Mask Example 


Note that the OS IR@ service routine uses and alters POKMSK., so 
alterations to the variable must be done with interrupts 
inhibited. If done at the interrupt level there is no problem, as 
the I bit is already seti if done at a background level then the 
SEI and CLI instructions should be used as shown in the examples. 


Setting Interrupt and Timer Vectors 


Because vertical-blank interrupts are generally kept enabled so that 
the frame counter RTCLOK is maintained accurately, there is a 
problem with setting the VBLANK vectors (VVBLKI and VVBLKD)? or 

the timer values (CDTMV1 through CDIMVS) directly. A VBLANK 
interrupt could occur when only one byte of the two-byte value had 
been updated, leading to undesired consequences. For this reason, 
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the SETVBYV CE4SF] routine is provided to perform the desired 
update in safe manner. The calling sequence is shown below: 


A = update item indicator 
t-~- S-fer timers 1 — 3S. 
& for immediate VBLANK vector VVBLKI. 
7 for deferred VBLANK vector VVBLKB. 
X = MSB of value to store. 
Y = LSB of value to store. 
JSR SETVBYV 


The A.X and Y registers can be altered. 
The display list interrupt will always be disabled on 
return, even if enabled upon entry. 


It is possible to fully process a vertical-blank interrupt 
during a call to this routine. 


When working with the System Timers, the vectors for timers 1 and 
2 and the flags for timers 3.4 and 5 should be set while the 


associated timer is equal to zero, then the timer should be set 
to its (nonzero)? value. 


Stack Content at Interrupt Vector Points 


The following table shows the stack content at every one of the 
RAM interrupt vector points: 
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The OS initializes these entries at power-up. 


RAM STACK CONTENT 


changing these vectors will alter system performance. 


Improperly 


INTERRUPT VECTOR DESCRIPTION OS RETURN CONTROL 
VDSLST £0200] Display list return, P 
VVBLKI €O222] +* VBLANK immediate return, P, A, X ¥ 
CDTMA1 £0226] System Timer 1 return, P, A, X, Y. return 
CDTIMA2 £0228) System Timer 2 return, P, A, X. Y. return 
VVBLKD [0224] # VBLANK defer. return, P, A, X, Y 
VIMIR@ £0216] +# IRG@ immediate return, P, A 
VSEROR C[O20C] +# Serial out ready return, P., A 
VSERIN £O20Aq] +# Serial in ready return, P, A 
VSEROC (COC20E] + Serial out compare return, P, A 
VTIMR1I (C6210) POKEY timer 1 return, P, A 
VTIMR2 CO212]) POKEY timer 2 return, P, A 
VTIMR4 £0214] POKEY timer 4 return, P, A 
VAEYBD £0208] + Keyboard data return, P., A 
VPRSED £0202] Serial proceed return, P. A 
VINTER £0204] Serial interrupt return, P, A 
VBREAK £0206] BRK instruction return, P. A 
Figure 6-4 Interrupt and Timer Vector RAM Stack Content Table 


Miscellaneous Considerations 


The following paragraphs list a set of miscellaneous 
considerations for the writer of an interrupt service routine. 


Restrictions on Clearing of "I" Bit 

Display list, immediate vertical-blank and System Timer #1 
routines should not clear the 6502 I bit. If the NMI leading to 
one of these routines occurred while an IRQ was being processed, 
then clearing the I bit will cause the IRG@ to re-interrupt with 
an unknown result. 


The OS VBLANK processor carefully checks this condition after the 
stage 1 process and before the stage 2 process. 

Interrupt Process Time Restrictions 
You should not write an interrupt routine that exceeds 400 msec. 
when added to the stage i VBLANK, if the serial I/O is being 


used. The SIO sets the CRITIC flag while serial bus I/0 is in 
progress. 
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Interrupt Delay Due to "WAIT FOR SYNC" 


Whenever a key is read from the keyboard, the Keyboard Handler 
sets WSYNC (€D4CA] repeatedly while generating the audible click 
on the console speaker. A problem occurs when interrupts are 
generated during the wait-for-sync period; the processing of such 
interrupts will be delayed by one horizontal scan line. This 
condition cannot be prevented. You can work around the condition 
by examining the line count VCOUNT [D40B] and delaying interrupt 
processing by one line when no WSYNC delay has occurred. 


FLOWCHARTS 


The following pages contain process flowcharts showing the main 
events that occur in the NMI and IR@ interrupt processes. 


om IRQ INTERRUPT PROCESS 


POKEY Y CLEAR 
TIMER 2? 
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CLEAR STATUS, 
SET BREAK FLG 
CLEAR S/S 


Y 
CLEAR 
STATUS — 
Y 
CLEAR 
STATUS — 
VBREAK (o" 


SERIAL 
PROCEED? 


SERIAL 
INTERR.? 


PULL REG A 
FROM STACK 
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NMI INTERRUPT PROCESS 


VDSLST 


PUSH REG A 
TO STACK 


VERTICAL 
BLANK? 


PUSH X & Y, 
CLEAR STATUS VVBLKI 


CRITICAL 
SECTION? 


N 
CLEAR 


RESTORE 


REGISTERS 
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7 SYSTEM INITIALIZATION 


Section 7 discusses the details of the power-up and 
system reset processes. The power-up process will be explained 
first, and then the system reset process will be explained in 
terms of its differences from the power-up process. 


Both power-up (also called coldstart}) and pressing (CSYSTEM. RESET] 
(warmstart})} will cause system initialization: In addition, there 
are vectors for these processes at E474 (system reset) and E477 
(power-up) so that they can be user-initiated. 


The power-up initialization process is a superset of the 

system reset initialization process. Power-up initializes both 
the OS and user RAM regions, whereas system reset initializes 
only the OS RAM region. In both cases, the OS calls the outer 
level software initialization entry points allow the application 
to initialize its own variables. 


Pressing the CSYSTEM. RESET] key produces an NMI interrupt. It 
does not perform a 6502 chip-reset. If the processor is locked 


up, the CSYSTEM. RESET] key cannot be sufficient to unlock it, and the 
system must have power cycled to clear the problem. 


POWER-UP INITIALIZATION (COLDSTART?) PROCEDURE 


The OS performs the following functions in the order shown, as 
part of the power-up initialization process: 


1. The following 6502 processor states are set: 


QO IRQ interrupts are disabled using the SEI instruction. 
's) The decimal flag is cleared using the CLD instruction. 
Oo The stack pointer is set to FF. 


2. The OS sets the warmstart flag WARMST COOO8] to O (false). 
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3. The OS tests to see if a diagnostic cartridge is in the A slot: 


o Cartridge address BFFC = OO? 
o The memory at BFFC is not RAM? 
o Bit 7 of the byte at BFFD = i? 


If all of the above tests are true, then control is passed to 
the diagnostic cartridge via the vector at BFFE. No return is 
expected. 


4. The OS determines the lowest memory address containing 
non-RAM. by testing the first byte of every 4K “block” to see 
if the content can be complemented. If it can be complemented, 
then the original value is restored and testing continues. If 
it can’t be complemented: then the content is assumed to be 
the first non-RAM address in the system. The MSB of the 
address is stored temporarily in TRAMSZ ([COOO6]. 


>. Zero is stored to all of the hardware register addresses shown 
below (most of that aren’t decoded by the hardware?: 


DOOOC through DOFF 
D200 through D2FF 
D300 through DSOFF 
D400 through D4FF 


4. The OS clears RAM from location OOCO8S., to the address 
determined in step 4, above. 


7. The default value for the “noncartridge" control vector 
DOSVEC COOOA] is set to point to the blackboard routine. At 
the end of initialization, control is passed through this 
vector if a cartridge does not take control. 


6S. The coldstart flag COLDST [0244] is set to -i (local use}. 


>. The screen margins are set: left margin = 2 right margin = 
39, for a 3B character physical line. The maximum line size of 
40 characters can be obtained by setting the margins to O and 
39. The OS insets the left margin because the two leftmost 
columns of the video picture on many television sets are not 
entirely visible on the screen. 


10. The interrupt RAM vectors VDSLST CO200] through VVBLKD (CO0224] 
are initialized. See Section 6 for the initialization values. 


11. Portions of the OS RAM are set to their required nonzero values 
as shown below: 
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id. 


14. 


id. 


ié. 


if. 


The CBREAK] key flag BRAKEY COO1i1] = -1 (false). 


The top of memory pointer MEMTOP COZES] = the lowest ®& 
non-RAM address (from step 4); MEMTOP will be altered 
later when the Screen Editor is opened in step 15. 


The bottom of memory pointer MEMLO CO2E7] = 0700; MEMLO 
can be changed later if there is either a diskette- or 
cassette-boot operation. 


The following resident routines are called for initialization: 


Screen Editor 

Display Handler 

Keyboard Handler 

Printer Handler 

Cassette Handler 

Central I/0 Monitor (CIO>} 
Serial I/0 Monitor (SIO) 
Interrupt processor 


The CSTART] key is checked, and if pressed, the cassette-boot 
request flag CKEY COO4Al] is set. 


6302 IRG interrupts are enabled using the CLI instruction. 
The device table HATABS COSIiA] is initialized to point to the 


resident handlers. See Section 9 for information relating to 
the Device Handler table. 


The cartridge slot addresses for cartridges B and A are 
examined to determine if cartridges are inserted, if RAM does 
not extend into the cartridge address space. 


If the content of location 9FFC is zero, then a JSR is 
executed through the vector at YFFE, thus initializing 
cartridge "“B". The cartridge is expected to return. 


If the content of location BFFC is zero, then a JSR is 
executed through the vector at BFFE, thus initializing 
cartridge "A". The cartridge is expected to return. 


IOCB #0 is set up for an OPEN of the Screen Editor (E>) and 
the OPEN is performed. The Screen Editor will use the highest 
portion of RAM for the screen and will adjust MEMTOP 
accordingly. If this operation should fail, the entire 
initialization process is repeated. 


A delay is effected to assure that a VBLANK interrupt has 
Occurred. This is done so that the screen will be established 
before continuing. 


If the cassette-boot request flag is set (see step 11 above), 
then a cassette-boot operation is attempted. See Section 10 & 
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for details of the cassette-boot operation. 


iS. If any of the three conditions stated below exists, an 
attempt is made to boot from the disk. 


There are no cartridges in the slots. 
Cartridge B is inserted and bit © of SFFD is 1. 
Cartridge A is inserted and bit O of BFFD is 1. 

See Section 10 for details of the diskette-boot operation. 


i9. The coldstart flag COLDST is reset to indicate that the 
coldstart process went to completion. 


20. The initialization process is now complete, and the 
controlling application is now determined via the remaining 
steps. 


If there is an A cartridge inserted and bit-2 of BFFD is 1, 
then a JMP is executed through the vector at BFFA. 


Or, if there is a B cartridge inserted and bit-2 of SFFD is 
1, then a JMP is executed through the vector at 9FFA. 


Or, a jyump is executed through the vector DOSVEC that can 
point to the blackboard routine (default case), cassette 


booted software or diskette booted software. BDOSVEC can be 
altered by the booted software as explained in Section 10. 


SYSTEM RESET INITIALIZATION (WARMSTART}) PROCEDURE 


The functions listed below are performed, in the order shown, as 
part of the system reset initialization process: 


A. Same as power-up step 1. 

B. The warmstart flag WARMST COOO08] is set to -i (true). 
Same as power-up steps 3 through 5. 

OS RAM is zeroed from locations O200-O3FF and 0010-007F. 


Same as power-up steps 9 through 16. 


1s I a ON 


If a cassette-boot was successfully completed during the 
power-up initialization, then a JSR is executed through the 
vector CASINI C0002]. See Section 10 for details of the 
cassefte-boot process. 
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G. Same as power-up step 18 except instead of booting the 
diskette software, a JGR is executed through the vector DOSINI 
COOOC] if the diskette-boot was successfully completed during the 
Power-up initialization. See Section 10 for details of the 
diskette-boot process. 


H. Same as power-up steps 19 and 20. 


Note that the initialization procedures and main entries for all 
software entities are executed at every system reset as well as 
at power up (see steps 14, 17, 18, 20, F and G}. If the 
user-supplied initialization/startup code must behave differently 
in response to system reset than it does to power-up, then the 
warmstart flag WARMST COOC8) should be interrogatedi WARMST = 0 
means power-up entry: else system reset entry. 
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8 FLOATING POINT ARITHMETIC PACKAGE 


This section describes the BCD floating point (FP) package that 
is resident in the OS ROM in both the models 400 and 800. 


The floating point package maintains numbers internally as &-byte 
quantities: a S-byte (10 BCD digit) mantissa with a i-byte 
exponent. BCD internal representation was chosen so that decimal 
division would not lead to the rounding errors typically found in 
binary representation implementations. 


The package provides the following operations: 


ASCII to FP conversion. 

FP to ASCII conversion. 

Integer to FP conversion. 

FP to integer conversion. 

FP add, subtract, multiply,and divide. 

FP logarithm, exponentiation, and polynomial evaluation. 
FP zero. load, store, and move. 


A floating point operation is performed by calling one of the 
provided routines (each at a fixed address in ROM) after having 
set one or more floating point pseudo registers in RAM. The 
result of the desired operation will also involve floating point 
pseudo registers. The primary pseudo registers are described 
below and their addresses given within the square brackets: 
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FRO £COD4] 6-byte internal form of FP number. 


FRI COOEOQ] = 6é-byte internal form of FP number. 

FLPTR COOFC] = @2-byte pointer (lo,hid to a FP. 
number. 

INBUFF [COOFS3S] = e-byte pointer (lo,hid to an ASCII text 
buffer. 

CIX €COF2] = i-byte index. used as offset to buffer 
pointed to by INBUFF. 

LBUFF COS80] = result buffer for the FASC routine. 


FUNC TIONS/CALLING SEQUENCES 


Descriptions of these floating point routines assume that 

a pseudo register is not altered by a given routine. The 
numbers in square brackets ECxxxxjJ are the ROM addresses of the 
routines. 


ASCII to Floating Point Conversion (AFP) 


Function: This routine takes an ASCII string as input and 
produces a floating point number in internal form. 


Calling sequence: 
INBUFF = pointer to buffer containing the ASCII 


representation of the number. 
CIX = the buffer offset to the first byte of the ASCII 


number. 
JSR AFP (CDS00] 
BCS first byte of ASCII number is invalid 
FRO = floating point number. 
CIX = the buffer offset to the first byte after the ASCII 


number. 


Algorithm: The routine takes bytes from the buffer until it 
encounters a byte that cannot be part of the number. The bytes 
scanned to that point are then converted to a floating point 
number. If the first byte encountered is invalid, the carry bit 
is set as a flag. 


Floating Point to ASCII Conversion (FASC) 


Function: This routine converts a floating point number from 
internal form to its ASCII representation. 
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Calling sequence: 
FRO = floating point number. 
JSR FASC (CDSE4] 
INBUFF = pointer to the first byte of the ASCII number. 
The last byte of the ASCII representation has the most 
significant bit (sign bit)d seti no EOL follows. 
Algorithm: The routine converts the number from its internal 
floating point representation to a printable form (ATASCII). The 


pointer INBUFF will point to part of LBUFF, where the result is 
stored. 


Integer to Floating Point Conversion (IFP} 


Function: This routine converts a 2-byte unsigned integer (0 to 
65535} to floating point internal representation. 


Calling sequence: 


FRO = integer (FRO+O0 = LSB, FRO+1 = MSB}. 
JSR IFP CD9AAI 
FRO = floating point representation of integer. 


Floating Point to Integer Conversion (FPI} 


Function: This routine converts a positive floating point number 
from its internal representation to the nearest 2-byte integer. 


Calling sequence: 


FRO = floating point number. 
JSR FPI (D9D2] 
BCS FP number is negative or >= 65535. 5 


FRO = 2-byte integer (FRO+O = LSB, FRO+i = MSB). 


Algorithm: The routine performs true rounding, not truncation, 
during the conversion process. 
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Floating Point Addition (FADD) 


Function: This routine adds two floating point numbers and checks © 
the result for out-of-range. 


Calling sequence: 


FRO = floating point number. 

FRi = floating point number. 

JSR FADD £CDA66] 

BCS out-of-range result. 


FRO = result of FRO + FR1. 
FRI is altered. 
Floating Point Subtraction (FSUB> 


Function: This routine subtracts two floating point numbers and 
checks the result for out-of-range. 


Calling sequence: 


FRO = floating point minuend. 
FRi = floating point subtrahend. 
JSR FSUB [DBA60] 

BCS out-of-range result. 


FRO = result of FRO —- FR1. 
FR1i is altered. 


Floating Point Multiplication (FMUL> 


Function: This routine multiplies two floating point numbers and 
checks the result for out-—-of-range. 


Calling sequence: 


FRO = floating point multiplier. 
FRi = floating point multiplicand. 
JSR FMUL CDBADB I 

BCS out-of-range result. 


FRO = result of FRO # FR1. 
FRI is altered. 
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Floating Point Division (FDIV) 


Function: This routine divides two floating point numbers and 
checks for division by zero and for result out-of-range. 


Calling sequence: 


FRO = floating point dividend. 

FRi = floating point divisor. 

JSR FDIV CDB28] 

BCS out-of-range result or divisor is zero. 


FRG = result of FRO / FRI. 
FRi is altered. 


Floating Point Logarithms (LOG and LOGiIO>} 


Function: These routines take the natural or base 10 logarithms 
of a floating point number. 


Calling sequence: 


FRO = floating point number. 


JSR LOG CDECBDI] for natural logarithm 
or 

JSR LOGiO CDED1I] for base 10 logarithm 

BCS negative number or overflow. 


FRO = floating point logarithm. 
FRi is altered. 


Algorithm: Both logarithms are first computed as base 10 
logarithms using a 10 term polynomial approximationi the natural 
logarithm is computed by dividing the base i0 result by the 
constant LOGIO(e}. 


The logarithm of a number Z is computed as follows: 


F # (10 ## Y} = Z where 1 <= F < 10 (normalization). 
i = LOGIO(CF) by 10 term polynomial approximation. 
LO0610(2Z2) = Y + L. LOG(Z)} = LOGIO(Z) / LOGIC(e?}. 


NOTE: This routine does not return an error if the number input 
is zero; the LOG1O result in this case is approximately -129. 5, 
which is not useful. 
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Floating Point Exponentiation (EXP and EXPi0) 
Function: This routine exponentiates. 
Calling sequence: 


FRO = floating point exponent (2). 


JSR EXP CDBCO] for e ## Z 

or 
JSR EXP10O0 CBDCC] for 10 ## Z 
BCS overflow. 


FRO = floating point result. 
FRi is altered. 


Algorithm: Both exponentials are computed internally as base 10, 
with the base e exponential using the identity: 
e ## X = 10 ##% ( X # LOGIOCe) >). 


The base 10 exponential is evaluated in two parts using the identity: 


10 *## X = 10 ## (I + Fd} = (10 ## I} # (10 #%# Fd} -- where I is the 
integer portion of X and F is the fraction. 


The term 1060 ## F is evaluated using a polynomial approximation, 
and 10 ## I is a straightforward modification to the floating 
point exponent. 


Floating Point Polynomial Evaluation (PLYEVL) 


Function: This routine performs an n degree polynomial 
evaluation. 


Calling sequence: 


X,Y = pointer (X = LSB) to list of FP coefficients (Ali?)} 
ordered from high order to low order (six bytes per 
coefficient). 

A = number of coefficients in list. 

FRO = floating point independent variable (Z}. 


JSR PLYEVL CDD40] 

BCS overflow or other error. 

FRO = result of A(nd)#Z##n + AlnN—-1)#ZH#4#nN-1 2... + ACLI#Z + 
ACO). 


FRi is altered. 


Algorithm: The polynomial P(Z) = SUM(i=0 to n> (ACid#Z##i)D is 
computed using the standard method shown below: 


P(Z) = (... CACnd#Z + ACn-1)98#Z + ... + ACIII#Z + ACO} 
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Clear FRO (ZFRO} 


Function: This routine sets the contents of pseudo register FRO 
to all zeros. 


Calling sequence: 
JSR ZFRO [CDA44] 


FRO = zero. 


Clear Page Zero Floating Point Number (2Fi> 


Function: This routine sets the contents of a zero-page floating 
point number to all zeroes. 


Calling sequence: 
X = Zero-~page address of FP number to clear. 
JSR ZFi CDA46] 


Zero-page FP number(X) = zero. 


Load Floating Point Number to FRO (FLDOR and FLDOP) 


Function: These routines load pseudo register FRO with the 
floating point number specified by the calling sequence. 


Calling sequences: 
X,Y = pointer (X = LSB) to FP number. 
JSR FLDOR CDD89] 
or 
FLPTR = pointer to FP number. 
JSR FLDOP ECDBDSD] 


FRO = floating point number (in either case). 
FLPTR = pointer to FP number (in either case). 
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Load Floating Point Number to FRI (FLDIR and FLDIP} 


Function: These routines load pseudo register FRI with the 
floating point number specified by the calling sequence. 


Calling sequences: 


As in prior description, except the result goes to FRi 
instead of FRO. FLDIR CDD98] and FLDIP CDDB9C. 


Store Floating Point Number From FRO (FSTOR and FSTCOP) 


Function: These routines store the contents of pseudo register 
FRO to the address specified by the calling sequence: 


Calling sequence: 
As in prior descriptions, except the floating point number 


is stored from FRO rather than loaded to FROG. FSTOR CDDA7I 
and FSTOGP {CDDAB]. 


Move Floating Point Number From FRO to FRI (FMOVE) 


Function: This routine moves the floating point number in FRO to 
pseudo register FR1. 


Calling sequence: 
JSR FMOVE CDDB6) 


FRI = FRO (FRO remains unchanged). 


RESOURCE UTILIZATION 


The floating point package uses the following RAM locations in 
the course of performing the functions described in this section: 


OOD4 through OOFF 
OS7E through OSFF 


All of these locations are available for program coding 
if your program does not call the floating point package. 
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IMPLEMENTATION DETAILS 


Floating point numbers are maintained internally as 46-byte 
quantities, with 5S bytes (10 BCD digits}? of mantissa and 1 byte 
of exponent. The mantissa is always normalized such that the 
most significant byte is nonzero (note “byte"“ and not "BCD 
digit}. 


The most significant bit of the exponent byte provides the sign 
for the mantissai O for positive and 1 for negative. The 
Temaining 7 bits of the exponent byte provide the exponent in 
excess 64 notation. The resulting number represents powers of 100 
decimal (not powers of 10). This storage format allows the 
mantissa to hold 10 BCD digits when the value of the exponent is 
an even power of 10, and 9 BCD digits when the value of the 
exponent is an odd power of 10. 


The implied decimal point is always to the immediate right of the 
first byte. An exponent less than 64 indicates a number less than 
1. An exponent equal to or greater than 64 represents a number 
equal to or greater than 1. 


Zero is represented by a zero mantissa and a zero exponent. To 
test for a result from any of the standard routinesi test either 
the exponent or the first mantissa byte for zero. 


The absolute value of floating point numbers must be greater than 
10##-98, and less than 10##+98, or be equal to zero. There is 
perfect symmetry between positive and negative numbers with the 
exception that negative zero 1S never generated. 


The precision of all computations is maintained at 9 or 10 
decimal digits. but accuracy 15 somewhat less for those functions 
involving polynomial approximations (logarithm and 
exponentiation). Also, the problems inherent in all floating 
point systems are present herei for example: subtracting two very 
nearly equal numbers, adding numbers of disparate magnitude, or 
successions of any operation, will all result in a loss of 
Significant digits. An analysis of the data range and the order 
of evaluation of expressions may be required for some types of 
applications. 


The examples below compare floating point numbers with their 
internal representations, as an aid to understanding storage 
format. All numbers prior to this point have been expressed in 
decimal notation, but these examples will use hexadecimal 
notation. Note that 64 decimal (the excess number of the 
exponent) is 40 when expressed in hexadecimal: 


Number: +0.02 = 2 * 10%#-2 = 2 * 100##-1 
Stored: GF O02 00 00 00 00 (FP exponent = 40 - 1} 


Number: -0.02 = -2 # 10##-2 = -2 * 100##-1 
Stored: BF O02 60 00 00 0O (CFP exponent = 80 + 40 - 1) 
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Number: #37.0 = 3.7 # 10##1 = 37 * 100##0 
Stored: 40 37 00 00 00 00 (FP exponent = 40 + QO} 


Number: ~-4. 60312486 # 108##11 = ~46.03... #* 100##5 e 
Stored: C5 46 03 O01 24 86 (FP exponent = 80 + 40 + 5) 


Number: 0.06 
Stored: OG 00 00 OO 00 00 (special case) 
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> ADDING NEW DEVICE HANDLERS/PERIPHERALS 

This section describes the interface requirements for a 
nonresident Device Handler that is to be accessed via the Central 
I/O utility (CiO}. The Serial bus I/0 utility (SI0Q) interface is 
defined for those handlers that utilize the Serial I/0 bus. 

The 1/0 subsystem is organized with three levels of software 
between you and your hardware: The CIO, the individual device 
handlers. and the SIO. 


The CIO performs the following functions: 


Logical device name to Device Handler mapping (on OPEN). 
I/O Control Block (IOCB) maintenance. 

Logical record handling. 

User buffer handling. 


The device handlers are below CIO. They perform the 
following functions: 


Device initialization on power-up and system reset. 
Device-dependent support of OPEN and CLOSE commands. 
Byte-at-a-time data input and output. 
Device-dependent special operations. 
Device-dependent command support. 

Device data buffer management. 


The SIO is at the bottom level (for Serial I/0 bus peripheral 
handlers}. It performs the following functions: 


Control of all Serial bus I/0, conforming to the bus 
protocol. 


Bus operation retries on errors. 
Return of unified error statuses on error conditions. 
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A separate control structure is used for communication at each 
interface, as follows: @ 


User/CiIod I/O Control Block (CIOCB} 
CIO/Handler Zero-page IOCB (ZIOCB?) 
Handler/SIO Device Control Block (DCB? 
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Where: ---- shows a control path. 
H#H#4#4 shows the data structure required for a path. 


Note the following: 
i. The Keyboard/Display/Screen Editor handlers don’t use 
SIO. 
2. The Diskette Handler cannot be called directly from CIO. 


3. The DCB is shown twice in the diagram. 


Figure 9-1 I/O Subsystem Flow Diagram 
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DEVICE TABLE 


The device table is a RAM-resident table that contains the 
single~character device name (e.g. K, D, C, etc}. and the 

handler address for each of the handlers known to CIO. The 

table is initialized to contain entries for the following 

resident handlers: Keyboard (K)., Bisplay (S). Screen Editor 

(Ed}, Cassette (CC), and Printer (P) at power-up and system reset. To 
install a new handler, some procedure must insert a device table entry 
after the table is initialized. 


The table format is shown below: 


HATABS COSiA] H device name 


table address 


> 
{ 
“he 
handler vector : +— one entry 
> 
H 
+ 


ee oe ee 


Figure 9-2 Device Table Format 


This 38-byte table will hold a maximum of 12 entries, with the 
last 2 bytes being zero. CIO scans the table from the end to 
the beginning (high to low address}; so the entry nearest the 
end of the table will take precedence in case of multiple 
occurrences of a device name.. 


The device name for each entry is a single ATASCII character, and 
the handler address points to the handler‘’s vector table, that 
will be described in the following section. 


CIO/HANDLER INTERFACE 


This section describes the interface between the Central I/0 
utility and the individual device handlers that are represented 
in the Device Table (as described in the preceding section). 
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Calling Mechanism 


6 Each handler has a vector table as shown below: 


pom ee + 

+ OPEN vector + Clow address>? 
$e ee ee + 

+ CLOSE vector + 

5 es + 

+ GETBYTE vector + 

pom He + 

+ PUTBYTE vector + 

a + 

+ GETSTAT vector + 

ope ee + 

+ SPECIAL vector + 

pe ee + 

+ JMP init code + 

+ + (high address} 
fee ee + 


Figure 9-3 Handler Vector Table 


The device table entry for the handler points to the first 
byte of the vector table. 


The first six entries in the table are vectors (lo,hi)d that 
contain the address - 1 of the handler routine that handles 
the indicated function. The seventh entry is a 6502 JMP 
instruction to the handler initialization routine. CIO uses 
only the addresses contained in this table for handler entry. 
Fach user/CIO command translates to one or more calls to one 
of the handler entries defined in the vector table. 


The vector table provides the handler addresses for certain 
fixed functions to be performed to CIO. In addition, operation 
parameters also must be passed for most functions. Parameter 
passing is accomplished using the 6502 A. X., and Y registers 
and an IOCB in page © named ZIOCB [0020]. In general, register 
A is used to pass data, register X contains the index to the 
originating IOCB, and register Y is used to pass status 
information to CIO. The zero-page IOCB., is a copy of the 
originating IOCB; but in the course of processing some 
commands, CIO can alter the buffer address and buffer length 
parameters in ZIOCB., but not in the originating IOCB (see 
Section 5 for information relating to the originating IOQCB?. 


See Appendix B for the standard status byte values to be 
returned to CIO in register Y. 
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The following sections describe the CiO/handler interface for 
each of the vectors in the handler vector table. 


Handler Initialization 


NOTE: This entry doesn’t appear to have any function for 
nonresident handlers due to a bug in the current OS -- the 
device table is cleared in response to system reset as 
well as power-up. This prevents this entry point from ever 
being called. The rest of this section discusses the 
intended use of this entry point. Conformation would be in 
order to allow compatibility with possible corrected 
versions of the OS in the future. 


The entry was to have been called on all occurrences of 
power-up and system reset; the handler is to perform 
initialization of its hardware and RAM data using a routine 


that assures proper processing of all CIO commands that follow. 


Functions Supported 


This section describes the functions associated with the first 
six vectors from the handler vector table. This section also 
presents a brief, device-independent description of the 


CiO/handler interface and recommended actions for each function 
vector. 


OPEN 


This entry is called in response to an OPEN command to CIO. The 
handler is expected to validate the OPEN parameters and perform 
any required device initialization associated with a device OPEN. 


At handler entry, the following parameters can be of interest: 


X 
Y 


index to originating IOCB. 
$92 (status = function not implemented by handler>. 


ICDNOZ £00217 = device number (1-4, for multiple device 
handlers}. 
ICBALZ/ICBAHZ [0024/0025] 


address of device/filename 
specification. 
device-specific information. 


ICAX1IZ/ICAX2Z COOC2ZA/002B] 


The handler attempts to perform the indicated OPEN and 
indicates the status of the operation by the value of the Y 
register. The responsibility for checking for multiple OPENs to 
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the same device or file, where it is illegal, lies with the 
handler. 

CLOSE 
This vector table entry is called in response to a CLOSE command 
to CIO. The handler is expected to release any held resources 
that relate specifically to that device/filename, and for output 
files to: 

i} send any data remaining in handler buffers to the device, 


2} mark the end of file 


3) update any associated directories, allocation maps. etc. 


At handler entry, the following parameters can be of interest: 


X 
Y 


index to originating IOCB. 
$92 (status = function not implemented by handler). 


ICDNOZ C0021] = device number (1-4, for multiple device 
handlers}. 
ICAX1Z/ICAX2Z COOC2ZA/002B] = device-specific information. 


The handler attempts to perform the indicated CLOSE and 
indicates the status of the operation by the value of the Y 
register. 


CIO releases the associated IOCB after the handler returns, 
regardless of the operation status value. 


GETBYTE 


This vector table entry is called in response to a GET 
CHARACTERS or GET RECORD command to CIO. The handler is 

expected to return a single byte in the A register, or return an 
error status in the Y register. 


At handler entry. the following parameters can be of interest: 


X 
$ 


index to originating IOCB. 
$92 (status = function not implemented by handler). 


ICDNOZ (COO021] = device number (1-4, for multiple device handlers). 
ICAXiZ/ICAX2Z COOC2A/O002B] = device-specific information. 


The handler will obtain a data byte directly from the device or from a 
handler-maintained buffer and return to CIO with the byte in the 
A register and the operation status in the Y register. 
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Handlers that do not have short timeouts associated with the 
reading of data (such as the Keyboard and Cassette Handlers), 
must monitor the CBREAK] key flag BRAKEY (COO11] and return with a 
status of $80 when a CBREAK] condition occurs. See Appendix L, 

ES: and Section i2 for a discussion of [BREAK] key monitoring. 


CIO checks for reads from device/files that have not been opened 


or have been opened for output only: the handler will not be called in 
those cases. 


PUTBYTE 


This entry is called in response to a PUT CHARACTERS or PUT 
RECORD command to CIO. The handler is expected to accept a single 
byte in the A register or return an error status in the Y 
register. 


At handler entry. the following parameters can be of interest: 


X = index to originating IOCB. 
Y = $92 (status = function not implemented by handler). 
A = data byte. 


ICDNOZ £00211] = device number (1-4, for multiple device 
handlers). 
ICAX1Z/ICAX2Z COO2ZA/O002B] = device-specific information. 


The handler sends the data byte directly to the device, or to a 
handler-maintained buffer, and returns to CIO with the operation 
status in the Y register. If a handler-maintained buffer fills, 
the handler will send the buffered data to the device before 
returning to CIO. 


CIO checks for WRITEs to device/files that have not been opened, 


or have been opened for input only. The handler will not be called in 
those cases. 


Now that the normal operation of PUTBYTE has been defined, a 
special case must be added. Any handler that will operate within 
the environment of the ATARI SK BASIC language interpreter has a 
different set of rules. Because BASIC can call the handler 
PUTBYTE entry directly. without going through CIO. the zero-page 
IOCB (ZIOCB) can or may not have a relation to the PUTBYTE call. 
Therefore, the handler must use the outer level IOCB to obtain 
any information that would normally be obtained from ZIOCB. Note 
also that the OPEN protection normally provided by CIO is 
bypassed (i.e. PUTBYTE to a non-OPEN device/file and PUTBYTE to a 
read-only OPEN}>. 
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GETSTAT 


This entry is called in response to a GET STATUS command to CIO. 
The handler is expected to return four bytes of status to memory 
or return an error status in the Y register. 


At handler entry. the following parameters can be of interest: 


X = index to originating IOCB. Y = $92 (status = function not 
implemented by handler>?. 


ICDNOZ C0021] = device number (1-4. for multiple device handlers>}. 
ICBALZ/ICBAHZ [0024/0025] = address of 
device/filename specification. 
ICAX1Z/ICAX2Z 
COO2Z2A/O002B] = device-specific information. 


The handler gets device status information from the device 
controller and puts the status bytes in DVSTAT CO2EA] through 
DVSTAT+3, and finally returns to CIO with the operation status 
in register Y. 


The IOCB need not be opened nor closed in order for you 

to request CIO to perform a GET STATUS operation: the handler 
must check where there are restrictions. See Section 5 for a 
discussion of the CIO actions involved with a GET STATUS 
operation using both open and closed IOCB’s, and note the impact 
of this operation on the use of the buffer address parameter. 


SPECIAL 


This handler entry is used to support all functions not handled 
by the other entry points, such as diskette file RENAME, display 
DRAW, etc. Specifically, if the IOCB command byte value is 
greater than $0D, then CIO will use the SPECIAL entry point. The 
handler must interrogate the command byte to determine if the 
requested operation is supported. 


At handler entry. the following parameters can be of interest: 


X 
¥ 


index to originating IOCB. 
$92 (status = function not implemented by handler>. 


ICDNOZ C0021] 


device number (1-4, for multiple device 
handlers?}. 

ICCOMZ C0022] = command byte. 

ICBALZ/ICBALH [0024/0025] buffer address. 
ICBLLZ/ICBLHZ CO0028/0029] buffer length. 

ICAXIZ/ICAX2Z COO2A/002B ] device-specific information. 


OPERATING SYSTEM CO16555 -- Section ? 
139 


The handler will perform the indicated operation, if possible, 
and return to CIO with the operation status in register Y. 


The IOCB need not be opened nor closed in order for you 

to request CIO to perform a SPECIAL operation: the handler 
must check where there are restrictions. See Section 5 for a 
discussion of the CIO actions involved with a SPECIAL 
operation using both open and closed IOCB’s. and note the 
impact of this on the use of the buffer address parameter. 


Error Handling 


Error handling has been simplified somewhat by having CIO handle 
outer level errors and having SIO handle Serial bus errors, 
leaving the handler to process the remaining errors. These 
errors include: 


out-of-range parameters. 
CBREAK] key abort. 
Invalid command. 

Read after end of file. 


The current handlers respond to errors using the following 
guidelines: 


They keep the recovery simple (and therefore predictable and 
repeatable). 


They Do not interact directly with you for recovery 
instructions. 


They lose as little data as possible. 


They make all attempts to maintain the integrity of file 


oriented device storage -- this involves the initial design 
of the structural elements as well as error recovery 
techniques. 


Resource Allocation 


Nonresident handlers needing code and/or data space in RAM should 
use the techniques listed below, to assure nonconflict with other 
parts of the OS. including other nonresident handlers. 
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Zero-Page RAM 


Zero-~page RAM has no spare bytes, and even if there were, there 
is no allocation scheme to support multiple program assignment of 
the spares. Therefore, the nonresident handler must save and 
restore the bytes of zero-page RAM it is going to use. The bytes 
to use must be chosen carefully, according to the following 
criteria: 


The bytes cannot be accessed by an interrupt routine. 
The bytes cannot be accessed by any noninterrupt code 
between the time the handler modifies the bytes and then 


Testores the original values. 


A simple save/restore technique would utilize the stack ina 
manner similar to that shown below: 


LDA COLCRS i (for example) 

PHA i SAVE ON STACK. 

LDA COLCRS+1 

PHA 

LDA HPOINT i HANDLER ‘’S POINTER. 


STA COLCRS 
LDA HPOINT+1 
STA COLCRS+1 


XXX (COLCRS}, Y i DO YOUR POINTER THING. 
PLA i RESTORE OLD DATA. 

STA COLCRS+1 

PLA 


STA COLCRS 


Note that the Display Handler or Screen Editor should not be 
called before restoring the original value of COLCRS, because 
COLCRS is a variable used by those routines. 


Nonzero-Page RAM 
There is no allocation scheme to support the assignment of 
fixed regions of nonzero-page RAM to any specific process, so the 


handler has three choices: 


1. Make a dynamic allocation at initialization time by 
altering MEMLO [O2E71]. 


ie 


Include the variables with the handler for RAM-resident 
handlers. This still involves altering MEMLO at the time 
the handler is booted. 


3. If the handler replaces one of the resident handlers (by 
removing the resident handler’s entry in the device 
table}, then the new handler can use any RAM that the 
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formerly resident handler would have used. 
Stack Space 


In most cases, there are no restrictions on the use of the stack 
by a handler. However, if the handler plans to push more than a 
couple dozen bytes to the stacki then it should do a stack 
overflow test, and always leave stack space for interrupt 
processing. 


HANDLER/SIO INTERFACE 


This section describes the interface between serial bus device 
handlers and the serial bus I[/0 utility (SIO}. SIO completely 
handles all bus transactions following the device-independent bus 
protocol. SIO is responsible for the following functions: 

Bus data format and timing from computer end. 

Error detection, retries and statuses. 


Bus timeout. 


Transfer of data between the bus and the caller’s buffer. 


Calling Mechanism 


SIO has a single entry point SIOV CE4S59] for all operations. The 
device control block (BCB} CO300] contains all parameters passed 
to SIO. The DCB contains the following bytes: 


DEVICE BUS ID -- BDEVIC £0300] 


The bus ID of the device is set by the handler prior to calling 
SIO (see Appendix I}. 


DEVICE UNIT # -—- DBUNIT [0301] 


This byte indicates that of n units of a given device type to 
access, and is set by the handler prior to calling SIO. This 
Value usually comes from ICDNOZ. SIO accesses the bus device 
whose address is equal to the value of DDEVIC plus BUNIT minus 1 
(the lowest unit number is normally equal to 1}. 


DEVICE COMMAND -- DCOMND [0302] 


The handler sets this byte prior to calling SIO. It will be sent 
to the bus device as part of the command frame. See Appendix I 
for device command byte values. 
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DEVICE STATUS -- DSTATS [C0303] 


This byte is bidirectional. The handler will use DSTATS to 
indicate to SIO what to do after the command frame is sent and 
acknowledged. SIO will use it to indicate to the handler the 
status of the requested operation. 


Prior fo an SIO call: 


7 6 
+—+-4+—4-—-4-4-4-4+- 


| { ‘ 


+ 
t ‘ H unused H 
a me ae ae te te te te 


Where: W,R = ©C.,O indicates no data transfer is associated with the 
operation. 


is invalid. 


After an SIO call: 


7 O 
Se Se eee See See ee ee 


+ 
} status code H 
$$ — HH HH HH 


See Appendix C for the possible SIO operation status codes. 
HANDLER BUFFER ADDRESS -- DBUFLO/DBUFHI [0304/0305] 


The handler sets this 2-byte pointer. It indicates the source 
or destination buffer for device data or status information. 


DEVICE TIMEOUT -- DTIMLO [0306] 


The handler sets this byte. It specifies the device timeout time 
in units of 64/60 of a second. For example, a count of 6 
specifies a timeout of 6.4 seconds. 


BUFFER LENGTH/BYTE COUNT -- DBYTLO/DBYTHI [£O0308/0309] 


The handler sets this 2-byte count for the current 

operation, and indicates the number of data bytes to be 
transferred into or out of the buffer. This parameter is not 
required if the STATUS byte W and R bits are both zero. These 
values indicate that no data transfer is to take place. 


WARNING: There is a bug in SIO that causes incorrect 


actions when the last byte of a buffer is in a memory 
address ending in $FF, such as I3FF., 42FF, etc. 
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AUXILIARY INFORMATION -- DAUX1/DAUX2 [CO30A/030B } 


The handler sets these @-bytes. The SIO includes them in the bus & 
command frame: they have device-specific meanings. 


Functions Supported 
SIO does not examine the COMMAND byte it sends to the device, 
because all bus transactions are expected to conform to a 
universal protocol. The protocol includes three forms, stated 
below (as seen from the computer): 

Send command frame. 

Send command frame and send data frame. 


Send command frame and receive data frame. 


The values of the W and R bits in the status byte select the 
command form. 


Error Handling 


SIO handles most of the serial bus errors for the handler, 
as indicated below: 


Bus timeout -- SIO provides a uniform command frame and data 
frame ACK byte timeout of 1/60 of a second - O / + 1/60. 

The handler specifies the maximum COMPLETE byte timeout 
value in DTIMLO. 


Bus errors -- SIO detects and reports VART overrun and 
framing errors. The sensing of these errors in any received 
byte will cause the entire associated frame to be considered 
bad. 


Data frame checksum error -- SIO validates the checksum on 
all received data frames and generates a checksum for all 
transmitted frames. 


Invalid response from device -- In addition to the error 
conditions stated above, SIO checks that the ACK and 
COMPLETE responses are proper (ACK = $41 and COMPLETE = 
$43). ACK stands for acknowledge. 


Bus operation retries -- SIO will attempt one complete command 
retry if the first attempt is not error free, where a complete 
command try consists of up to 14 attempts to send (and 

acknowledge) a command frame: followed by a single attempt to 
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receive the COMPLETE code and possibly a data frame. 


NOTE: There is a bug in the retry logic for data writes, 
such that if the command frame is acknowledged by the 


controller, but the data frame is not acknowledged, then SIO 


will retry indefinitely. 


Unified error status codes -- SIO provides device-independent 
codes (see Appendix C}. 


SERTAL 1/0 BUS CHARACTERISTICS AND PROTOCOL 


This section describes: 


Oo The electrical characteristics of the ATARI 400 
and ATARI 800 Home Computers serial bus 
o The use of the bus to send bytes of data, 
0 The organization of the bytes as "frames" (records), 
0 The overall command sequences that utilize frames 


and response bytes to provide computer/peripheral communi 


Hardware/Electrical Characteristics 


The ATARI 400 and the ATARI SOO Home Computers 

communicate with peripheral devices over a 19,200 baud 
asynchronous serial port. The serial port consists of a serial 
DATA OUT (transmission) line, a serial DATA IN (receiver?) line 
and other miscellaneous control lines. 


Data is transmitted and received as 8 bits of serial data (LSB 
sent first) preceded by a logic zero start bit and succeeded 
by a logic one stop bit. The serial DATA OUT is transmitted as 
positive logic (+4v = one/true/high, Ov = zero/false/low}. The 
serial DATA OUT line always assumes its new state when the 
serial CLOCK OUT line goes high; CLOCK OUT then goes low in 
the center of the DATA OUT bit time. 


An end view of the Serial bus connector at the computer or 


peripheral is shown below (the cable connectors would of 
course be a mirror image): 
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where: i = computer CLOCK IN. 
2 = computer CLOCK OUT. 
3 = computer BATA IN. 
4 = GND. 
2 = computer DATA OUT. 
& = GND. 
7 = COMMAND-. 
8 = MOTOR CONTROL. 
9 = PROCEED-. 
10 = +5v/READY. 
11 = computer AUDIO IN. 
12 = +1e2v. 
13 = INTERRUPT-. 


Figure 9-4 Serial Bus Connector Pin Descriptions 


CLOCK IN is not used by the present OS and peripherals. This 
line can be used in future synchronous communications schemes. 


CLOCK OUT is the serial bus clock. CLOCK OUT goes high at the 
start of each DATA OUT bit and returns to low in the middle of 
each bit. 


DATA IN is the serial bus data line to the computer. 
Pin 4 GND is the signal/shield ground line. 

DATA OUT is the serial bus data line from the computer. 
Pin & GND is the signal/shield ground line. 


COMMAND- is normally high and goes low when a command frame is 
being sent from the computer. 


MOTOR CONTROL is the cassette motor control line (high=on., 
low= off}. 


PROCEED- is not used by the present OS and peripheralsi this line 
is pulled high. 


+Sv/READY indicates that the computer is turned on and ready. This 
line can also be used as a +5 volt supply of SOma current rating 
for ATARI peripherals only. 


AUDIO IN accepts an audio signal from the cassette. 
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+12V is a +12 volt supply of unknown current rating for ATARI 
peripherals only. 


INTERRUPT- is not used by the present OS and peripherals: this 
line is pulled high. 


There are no pin reassignments made in the Serial bus cable, 


sO pin 3, the computer‘’s DATA IN line, is the peripheral ‘s 
data output linei and similarly for pin 5. 


Serial Port Electrical Specifications 


Peripheral input: 


ViH = 2. Ov min. 

Vil = 0. 4v max. 

IiH = 20ua. max. @ VIH = 2. Ov 
Iit = Sua. max. @ ViL = . 4v 


Peripheral output (open collector bipolar}: 


O.4v max. @ 1.6 ma. 
4.5v min. with external 100Kohm pull-up. 


Vec/READY input: 


ViH = 2.0v min. @ I1H = ima. max. 
Vit = 0. 4v max. 
Input goes to logic zero when open. 


Bus Commands 
The bus protocol specifies that all commands must originate from the 
computer, and that peripherals will present data on the bus only when 
commanded to. Every bus operation will go to completion before 
another bus operation is initiated (no overlap}. An error detected at 
any point in the command sequence will abort the entire sequence. 
A bus operation consists of the following elements: 

Command frame from the computer. 

Acknowledgement (ACK) from the peripheral. 


Optional data frame to or from the computer. 


Operation complete (COMPLETE) from the peripheral. 
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Command Frame 


The serial bus protocol provides for three types of commands: 1) data @ 
send, 2) data receive and 3} immediate (no data -- command only). 

There is a common element in all three types, a command frame 

consisting of five bytes of information sent from the computer 

while the COMMAND- line is held low. The format of the command 

frame 15 

shown below: 


© ceieaieianaieetaiadaetededetedaeten + 
i device ID H 
Hh ne + 
: command i 
+—-—-—--~--—-~—--- + 
t auxiliary #1 
+———————— + 
i auxiliary #2 
+ —-—— ~ 
H checksum { 
$e + 

Figure 9-5 Serial Bus Command Frame Format 


The device ID specifies that of the serial bus devices is being 
addressed (see Appendix I for a list of device IDs}. 


The command byte contains a device-dependent command (see 
Appendix I for a list of device commands}. 


The auxiliary bytes contain more device-dependent information. 
The checksum byte contains the arithmetic sum of the first four 
bytes (with the carry added back after every addition?. 

Command Frame Acknowledge 
The peripheral being addressed would normally respond to a 
command frame by sending an ACK byte ($41) to the computer; if 


there is a problem with the command frame, the peripheral should 
not respond. 


Data Frame 
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Following the command frame (and ACK?) can be an optional data 
frame that is formatted as shown below: 


Se ~ 
{ { 
£ ‘ 
t { 
{ t 
t data H 
H bytes H 
4 t 
{ t 
tn ee eee + 
H checksum { 
ow ree + 


This data frame can originate at the computer or at the device 
controller, depending upon the command. Current device 
controllers expect fixed-length data frames as does the computer, 
where the data frame length is a fixed function of the device 
type and command. 


The checksum value in the data frame is the arithmetic sum of all 
of the frame data preceding the checksum, with the carry from 
each addition being added back (the same as for the command 
frame}. 


In the case of the computer sending a data frame to a peripheral, 
the peripheral is expected to send an ACK if the data frame is 
acceptable, and send a NAK ($4E), or do nothing if the data frame 
is unacceptable. See the first flowchart in Section 9. 


Operation Complete 


A peripheral is also expected to send an operation-COMPLETE byte 
($43) at the time the commanded operation is complete. The 
location of this byte in the command sequence for each command 
type is shown in the timing diagrams in Section 9. If the 
operation cannot go to normal, error-free completion, the 
peripheral should respond with an ERROR byte ($45) instead of 
COMPLETE. 
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Bus Timing 


This section provides timing diagrams for the three types of ®@ 
command sequences: data send, data receive, and immediate. 


DATA SEND sequence: 


——— +} a a ns i ss cs cs ae es cre es ere ees ee ene care cae cae ene ete cee ene eee ee 
COMMAND—- : 
Fie ee + 
Se + +——— ff f—-——+ 
DATA OUT i emnd | i: data | 
nt EEE pee TESS Stas | SS ee 
po + +o ~p mob 
DATA IN f 4 i ot i 
ee + +—- tf ft te 
ACK ACK CMPL 
tO ti t2 t3 t4 tS 
DATA RECEIVE sequence: 
— oe oe oe we sem ese cee cane eee eam coms ones ce sna eres nee ene sane sees cae sees seme snes sme sense sent sen snee srtn cose cute some seme seems see soem sees cos ue 
COMMAND— H } 
pm me + 
$a + 
DATA OUT i cmnd { 
nena ie Re pe a re ee aie pan rer Sr A 
ta + +—-+ 4----/ /---—-+ 
DATA IN oA ee eS data { 
oe ee ee + +-—-//--+ +--+ frame + 
ACK CMPL 
tO ti t2 tS 
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IMMEDIATE sequence: 


<> 
COMMAND— 

ep me ee re ee wee me 

pa ee ee 
DATA OUT 1 eomnd 

—-—--+frame 

DATA IN 

tO 


Figure 9-6 Serial Bus 


te mc ce sae ee ca ee ne ee ec ae ee cn en see ee Sem cee ee cee Ses san ee Sr sae em see em et 

oF 

—+ 

a eaeee coves cance S060 GUNG? SUOS> come GnEED GuEES GUESS GEEE: GESGD SONED GEES GEGED GOED SOnGD SOGES GOEDD GONE GIES? GONED GREED SONI SGO=ED Steet GET coaeD GeuGD cness GUESS Gou=D SetD exes eoeEe Gram 
at ++ 

--——— + $a ef f a tte 
ACK CMPL 

ti t2 ¢s 


Timing Diagram 


The computer generates a delay (tO) between the lowering of COMMAND- 


and the transmission of 


computer tO (min) = 
computer tO (max) = 


peripheral tO (min} 
peripheral tO (max) 


the first byte of the command frame. 


750 mictrosec. 
1600 microsec. 


= ?? 
= >}? 


The computer generates a delay (ti) between the transmission of 
the last bit of the command frame and the raising of the COMMAND- 


line. 


computer ti (min) 
computer ti (max} 


peripheral t1 (min>} 
peripheral t1 (max) 


650 mictrosec. 
950 microsec. 


2? 
? ? 


The peripheral generates a delay (t2) between the raising of 
COMMAND- and the transmission of the ACK byte by the peripheral. 


computer te (min) = 
computer t2 (max) = 


peripheral te (min? 
peripheral t2 (max} 


O micTrosec. 
16 msec. 


= 2? 
= 2? 
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The computer generates a delay (tG) between the receipt of the 
last bit of the ACK byte and the transmission of the first bit of 
the data frame by the computer. 


computer €3 (min? = 1000 microsec. 
computer t3 (max) = 1800 microsec. 
peripheral t3 (min} ?? 
peripheral t3 (max>} 


to oil 
+ J “J 
~ ° 


The peripheral generates a delay (t4) between the transmission of 
the last bit of the data frame and the receipt of the first bit 
of the ACK byte by the computer. 


computer t4 (min) = 850 microsec. 
computer t4 (max) = 16 msec. 


—— 


ve 


peripheral t4 (min? 
peripheral t4 (max) 


The Peripheral generates a delay (t5) between the the receipt of 
the last bit of the ACK byte and the first bit of the COMPLETE 
byte by the computer. 


computer €5 (mind = 250 microsec. 
computer €5 (max) = 255 sec. (handler-dependent)} 


+? 
N/A 


peripheral €5 (min) 
peripheral €5 (max) 


HANDLER ENVIRONMENT 


Nonresident handlers can be installed in at least three different 
manners: 


i. As booted software from diskette or cassette. 

2. Resident in a cartridge (A or B). 

3. Downloaded from a serial bus device. 
This section will discuss the basic mechanisms for handler 
installation for these environments. In order to fully utilize the 


information in this section, you must have read and understood the 
following sections: 


Proetam environments =... 3. >. 2 < -Seeeion:S 
Maet TOOL RN oe eS ee sas Se eee 4 
Memory dynamics. .. oe gs ee a Oe ee ee are 
System initialization. 23 . Section 7 
Adding new device handlers/peripherals . gection 9 
Program environment and initialization . Section 10 
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Bootable Handler 


The diskette- or cassette-booted software will insert the 
handler‘’s vector table pointer and name to the device table 
whenever the booted software’s initialization entry point is 
entered (on power-up and system reset}. Remember that both 
power-up and system reset clear the device table of all but the 
resident handler entries. 


Cartridge Resident Handler 


The cartridge software will insert the handler’s vector table 
pointer and name to the device table whenever the cartridge’s 
initialization entry point is entered (on power-up and 

system reset). Remember that both power-up and system reset 
clear the device table of all but the resident handler entries: 
therefore the device table must be reestablished by the 
handler-initialization procedure upon every entry. 


FLOWCHARTS 


The following pages contain process flowcharts showing the SIO 
and peripheral actions for the Serial bus command forms. 
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PERIPHERAL’S COMMAND FRAME PROCESSING 


WAIT FOR 
HIGH TO LOW 
TRANSITION 
ON COMMAND- 


GET NEXT 5 
BYTES ON 
THE BUS 


WAIT FOR 
COMMAND- 
TO GO HIGH 


YES 


VALID 
AUX DATA 


YES 


SEND ACK 
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DATA FRAME TO PERIPHERAL 


SETUP TO 


READ DATA 
FRAME 


GET N BYTES TIMEOUT 
FROM BUS 


SEND ACK 


SEND NAK 


ATTEMPT TO 
PERFORM 
INDICATED 

OPERATION 


OPERATION 
OK? 
YES 


SEND 
COMPLETE 
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DATA FRAME TO COMPUTER 


ATTEMPT TO 
PERFORM 
INDICATED 

OPERATION 


OPERATION 
OK? 
SEND 

COMPLETE 


SEND DATA 


SEND ERR 


IMMEDIATE 


ATTEMPT TO 
PERFORM 
INDICATED 

OPERATION 


OPERATION 
OK? 
SEND 
COMPLETE 
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10 PROGRAM ENVIRONMENT AND INITIALIZATION 


This section discusses possible alternative software environments 
using OS Configurations. Environments other than those discussed 
here are also possible. A thorough understanding of the power-up 
and system reset processes (see Section 7} will be necessary to 
evaluate all alternative environments. 


CARTRIDGE 


Most games (and some language processors) are supported via the 
cartridge environment. The cartridge resident software is in 
control of the system, sometimes using the OS and sometimes not. 
A cartridge can specify whether the diskette is to be booted at 
power-up time, whether the cartridge is to provide the 
controlling software, or whether the cartridge is a special 
diagnostic cartridge. These options are specified by bits in the 
cartridge header, as shown below: 


ee + 
H cartridge H BFFA (9FFA for cartridge B) 
be + 
i start address i; 
pe ee + 
H 00 H 
4 ee + 
it option byte { 
fae ee ee + 
cartridge H 
he —+ 
( init address | BFFF (9FFF for cartridge B) 
or ee + 


Figure 10-1 Cartridge Header Format 


The byte of "O00" is used to allow the OS to determine when a 
cartridge is inserted; locations BFFC and 9FFC will not read zero 
when there is neither RAM at those locations nor a cartridge 
inserted. RAM is differentiated from a cartridge by its ability 
to be altered. 
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The option byte has the following option bits: 


bit 0 = @, then do not boot the diskette. 
1, then boot the diskette. 


Bit 2 = 6, then init but do not start the cartridge. 
1, then init and start the cartridge. 
bit 7 = @ then cartridge is not a diagnostic cartridge. 


1, then cartridge is a diagnostic cartridge and control 
will be given to the cartridge before any of the OS 
is initialized (JMP (BFFE}>. 


The cartridge init address specifies the location to which the OS will 
JSR during all power-up and system reset operations. As a minimum, 
this vector should point to an RTS instruction. 


The cartridge start address specifies the location to which the OS 
will JMP during all power-up and system reset operations, if 

bit i of the option byte is = 1. The application should examine 
the variable WARMST COOO8) if system reset action is to be 
different than power-up (WARMST will be zero on power-up and 
nonzero thereafter}. 


Cartridge Without Booted Support Package 


A cartridge that does not specify the diskette-boot option and does 
not support the cassette-boot possibility can use lower memory 
(from O480 to the address in MEMTOP CO2ES]) in any way it sees 

Fit. 


Cartridge With Booted Support Package 

A cartridge that does specify the diskette-boot option or does 
support the cassette-boot possibility must use some care in its 
use of lower memory. The following regions are defined: 


O480-O46FF is always available to the cartridge. 
MEMLO/MEMTOP region is always available to the cartridge. 


DISKETTE-BOOTED SOFTWARE 


Software can be booted from the disk drive at power-up time in 
response to one of the following conditions: 
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Neither Cartridge A nor B is inserted. 


Cartridge A is inserted and has bit OC of its option byte 
CBFFDI] = 1. 


Cartridge B is inserted and has bit OG of its option byte 
COFFDI = 1. 


If any of these conditions are met, the OS will attempt to read 
the boot record from sector #1 of disk drive 1 and then transfer 
control to the software that was read in. The exact sequence of 
operations will be explained later in this section. 


Diskette-Boot File Format 


The key region of a diskette-boot file is the first six bytes, which 
are formatted as shown below: 


pe ee + 
H flags i first byte 
De + 
i # of sectors H 
a ee + 
i memory address |; 
ee —+ 
t to start load H 
$e + 
{ init H 
+= +e 
{ address i sixth byte 
ee ee + 
H boot H 
i continuation : 
H code H 


Figure 10-2 Diskette-Boot File Format 


The first byte is stored in DFLAGS ([O0240], but is otherwise 
unused. It should equal zero. 


The second byte contains the number of 128-byte diskette sectors 
to be read as part of the boot process (including the record 
containing this information). This number can range from 1 to 
255, with CO meaning 256. 
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The third and fourth bytes contain the address (lo,hi)d at which to 
start loading the first byte of the file. 


The fifth and sixth bytes contain the address (lo,hi} to which the 
booter will transfer control after the boot process is complete 
and whenever the (CSYSTEM. RESET] key is pressed. 


The Diskette File Management System (FMS) has extra bytes assigned to 
its boot record, but this is a special case of the generalized 
diskette-boot and is discussed in Section §. 


Diskette-Boot Process 


If no cartridge is installed, then the diskette will follow these 
steps to boot up: 


1. Read the first diskette record to the cassette buffer [0400]. 
2. Extract information from the first six bytes: 


Save the flags byte to DFLAGS (0240,1]. Save the # of sectors 
to boot to DBSECT £0241,1]. Save the load address to BOOTAD 
CO242,2)]. Save the initialization address in BOSINI [COOCC, 2]. 


3. Move the record just read to the load address specified. 
4. Read the remaining records directly to the load area. 


>. JSR to the load address+6é where a multistage boot process can 
continue. The carry bit indicates the success of this 
operation (carry set = error, carry reset = success). 


NOTE: During step 5, after the initial boot process is 
complete, the booter will transfer control to the seventh byte 
of the first record. The software should continue the boot 
process at this point, if it is a multistage boot. The value 
of MEMLO CLO2E7] should point to the first free RAM location 
beyond the software just booted. It should be established by 
the booted software as shown below: 


LBA #END+1 ; SET UP LSB. 
STA MEMLO 

STA APPMHI 

LDA #END+1/296 i SET UP MSE. 
STA MEMLO+1 

STA APPMHI+1 


If the booted software is to take control of the 
system at the end of the boot operation, the 
vector DOSVEC [COOCA] must be set up by the 
application at this time; DOSVEC points to the 
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Testart entry for the booted application. If the 
booted software is not to take control, then 
DOSVEC should remain unchanged. 


LDA #RESTRT i RESTART LSB. 
STA DOSVEC 

LBA #RESTRT/256 

STA DOSVEC +1 


& JGR indirectly through DOSINI for initialization of the 
application; the application will initialize and return. 


NOTE: The OS enters the initialization point on every 
system reset and power-up. Internal initialization can take 
place during system reset and power-up as well. Initialization 


can also be deferred until Step 7 for controlling 
applications. 


7. JMP indirectly through DOSVEC to transfer control to the 
application. 


NOTE: Pressing the CSYSTEM. RESET] key after the application 
is fully booted will cause steps 6&6 and 7 to be repeated. 


Sample Diskette-Bootable Program Listing 


This skeletal program can be booted from the diskette. It retains 
control when it is entered. 


; THIS IS THE START OF THE PROGRAM FILE. 


PST= $0700 i (OR SOME OTHER LOCATION). 
to PST i; €, ORG). 


i THIS IS THE diskette-boot CONTROL INFORMATION. 


etre 0 i 
.BYTE PND-PST+127/128 i NUMBER OF RECORDS. 
.WORD PST i MEMORY ADDRESS TO START LOAD. 


.WORD PINIT PROGRAM INIT. 
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i THIS IS THE START OF THE BOOT CONTINUATION. 


LDA #P ND i; ESTABLISH LOW MEMORY LIMITS. 
STA MEMLO 

STA APPMHI 

LDA #PND/256 

STA MEMLO+ 1 

STA APPMHI+1 


LDA #RESTRT ; ESTABLISH RESTART VECTOR. 

STA DOSVEC 

LDA #RESTRT/256 

STA DOSVEC+1 

CLC ; SET FLAG FOR SUCCESSFUL BOOT. 
RTS 


i APPLICATION INITIALIZATION ENTRY POINT. 


PINIT RTS ; NOTHING TO DO HERE FOR ... 
i ... CONTROLLING APPLICATION. 


i THE MAIN BODY OF THE PROGRAM FOLLOWS. 
RESTRT=# 
i THE MAIN BODY OF THE PROGRAM ENDS HERE. 


PND= # i ‘PND’ = NEXT FREE LOCATION. 
. END 


Figure 10-3 Diskette-Bootable Program Listing Example 


Program to Create Diskette-Boot Files 


This section provides a program that can be used to make bootable 
files on diskettes. The program given is not the only one possible, 
and no claims are made as to its elegance. 
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Shown below is a listing of the program to create diskette-boot files. 


i THIS PROGRAM WRITES A SINGLE "FILE" TO THE DISKETTE AND IS 
i USED IN CONJUNCTION WITH A PROCEDURE TO MAKE DISKETTE- 

+ BOOTABLE FILES. THE FOLLOWING TWO SYMBOLS MUST BE EQUATED 
i USING THE MEMORY LIMITS OF THE PROGRAM TO BE COPIED: 


‘PST’ = PROGRAM START ADDRESS (SEE SAMPLE PROGRAM). 
‘PND’ = PROGRAM END ADDRESS (SEE SAMPLE PROGRAM}. 
SECSIZ=128 i DISKETTE SECTOR SIZE. 


PST= $0700 
PND= $1324 
FLEN= PND-PST+SECSIZ-1i/SECSIZ i; # OF SECTORS IN FILE. 


+= $BOCO0 i THIS PROGRAM‘’S ORIGIN. 


BOOTB BRK i ##% LOAD APPLICATION ##+# 
; SET UP DEVICE CONTROL BLOCK FOR DISKETTE HANDLER CALL 


LDA #F LEN i # OF SECTORS TO WRITE. 
STA COUNT 


LDA #1 i DISK DRIVE #1. 
STA DUNIT 


LDA # ‘W ; SET UP FOR WRITE WITH CHECK. 
STA DCOMND 


LDA #PST ji POINT TO START OF APPLIC. PROG. 
STA DBUFLO 

LDA #PS1T/256 

STA DBUFHI 


LDA #01 ; SET UP STARTING SECTOR # = 0001. 
STA DAUX1 
LDA #00 


STA DAUX2 
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i NOW WRITE THE FILE ONE SECTOR AT A TIME. 


BOTO10O JSR DSKINV i WRITE ONE SECTOR. 
BMI DERR ; ERROR. 
LDA DBUFLO i INCREMENT MEMORY ADDRESS. 
CLC 


ADC #SECSIZ 
STA DBUFLO 

LDA DBUFHI 

ADC #0 

STA DBUFHI 


INC DAUX 1 i INCREMENT SECTOR #. 
BNE BOTO20 
INC DAUX2 


BOTO2O DEC COUNT ; MORE SECTORS TO WRITE? 
BNE BOTO10 i; YES. 
BRK i STOP WHEN DONE. 

DERR BRK i STOP ON ERROR. 

COUNT #=#+1 i; SECTOR COUNT. 


i THIS IS THE CARTRIDGE HEADER 


+= tBFFO9 i "A" CARTRIDGE. 
INIT RTS 

.WORD BOOTB 

.BYTE @.4 

.WORD INIT 

. END 


CASSETTE-BOOTED SOFTWARE 


You can boot software from the cassette as well as from the 
diskette, at power-up. The following requirements must be met in order 
to boot from the cassette: 


2) You must be pressing the CSTARTI] key as power is 
applied to the system. 


o A cassette tape with a proper boot format file must be 
installed in the cassette drive, and the PLAY button must be 
pressed. 
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0 When you are given the audio prompt by the cassette 
handler you must press the CRETURN] key. 


If all of these conditions are met, the OS will read the boot file 
from the cassette and then transfer control to the software that 
was Tead in. The exact sequence of operations will be explained 
later in this section. 


Cassette-Boot File Format 


The key region of a cassette-boot file is the first six bytes. that 
are formatted as shown below: 


+ — + 
pe ee + 
i # of Records H 
Spm ee ee + 
i: Memory Address | 
oe ee 
i To Start Load H 
es + 
i Init H 
ae ~ 
H address { 
rs + 


The first byte is not used by the cassette-boot process. 


The second byte contains the number of 128-byte cassette records to 
be read as part of the boot process (including the record 
containing this information). This number can range from 1 to 255, 
with O meaning 2564. 


The third and fourth bytes contain the address (lo,hi} to which the 


booter will transfer control after the boot process is complete and 
whenever the (CSYSTEM. RESET] key is pressed. 


Cassette-Boot Process 

The cassette-boot process is described step-by-step for a 
configuration in that no cartridge is installed and no diskettes are 
attached. For the general case see Section 7. 


1. Read the first cassette record to the cassette buffer. 


2. Extract information from the first six bytes: 
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Save the # of records to boot. Save the load address. Save 
the initialization address in CASINI [0002] 


3. Move the record just read to the load address specified. 
4. Read the remaining records directly to the load area. 


>. JSR to the load address+S where a multistage boot process 
can continue; the carry bit will indicate the success of 
this operation (carry set=error, carry reset=success). 


& JSR indirectly through CASINI for initialization of the 
application: the application will initialize and return. 


7. JMP indirectly through DOSVEC to transfer control to the 
application. 


Pressing the CSYSTEM. RESET] key after the application is fully booted 
will cause steps 6 and 7 to be repeated. 


NOTE: After the initial boot process is complete, the booter will 
transfer control to the seventh byte of the first record: at this 
point the software should continue the boot process (if it is a 
multistage boot) and then stop the cassette drive, which due to a 
system bug will still be running, using the following instruction 
sequence: 


LDA #$3C 

STA PACTL CD302] 
The application should then set a value in MEMLO (€0237] that 
points to the first free RAM location beyond the software just 
booted, as shown below: 


LDA #END+ 1 

STA MEMLO 

STA APPMHI 

LDA #END+1/2596 
STA MEMLO+1 
STA APPMHI+1 


If the booted software is to take control of the system at the end 
of the boot operation, the vector DOSVEC [COOOA] must be set up by 
the application at this time; DOSVEC points to the restart entry 
for the booted application. If the booted software is not to take 
control, then DOSVEC should remain unchanged. 


LDA #RESTRT i; RESTART LSB 
STA DOSVEC 

LDA #RESTRT/256 

STA DOSVEC+1 


NOTE: The initialization point is entered on every system reset 
and power-up; internal initialization can take place here. 
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For controlling applications initialization can also be deferred 
until step 7. 


Sample Cassette-Bootable Program Listing 


Shown below is a skeletal program that can be booted from the 
cassette and that retains control when it is entered. 


i THIS IS THE START OF THE PROGRAM FILE. 
PST= $0700 i (OR SOME OTHER LOCATION). 
t= PST i (€. ORG). 


i THIS IS THE cassette-boot CONTROL INFORMATION. 


. BYTe -@ i (DOESN‘’T MATTER?>. 

.BYTE PND-PST+127/128 i NUMBER OF RECORDS. 

.WORD PST i MEMORY ADDRESS TO START LOAD. 
.WORD PINIT + PROGRAM INIT. 


i THIS IS THE START OF THE BOOT CONTINUATION. 


LDA #$.3C i STOP THE CASSETTE. 
STA PACTL 


LDA #P ND i; ESTABLISH LOW MEMORY LIMITS. 
STA MEMLO 

STA APPMHI 

LDA #PND/256 

STA MEMLO+1 

STA APPMHI+1 


LDA #RESTRT i ESTABLISH RESTART VECTOR. 
STA DOSVEC 

LDA #RESTRT/256 

STA DOSVEC+1 


CLC i SET FLAG FOR SUCCESSFUL BOOT. 
RTS 


i APPLICATION INITIALIZATION ENTRY POINT. 


PINIT RTS i NOTHING TO DO HERE FOR ... 
i ... CONTROLLING APPLICATION. 


i THE MAIN BODY OF THE PROGRAM FOLLOWS. 
RESTRT=+# 


© | 


THE MAIN BODY OF THE PROGRAM ENDS HERE. 
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PND= # i ‘PND’ = NEXT FREE LOCATION. 
. END 


Figure 10-4 Sample Cassette-Bootable Program 


Program to Create Cassette-Boot Files 


This section provides a program listing that can be used to make 
bootable files on cassette tapes. The program given is not the only 
one possible, and no claims are made as to its elegance. 


Shown below is a listing of the program to create a cassette-boot 
file: 


THIS PROGRAM WRITES A SINGLE FILE TO THE CASSETTE AND IS 
USED IN CONJUNCTION WITH A PROCEDURE TO MAKE CASSETTE- 
BOOTABLE FILES. THE FOLLOWING TWO SYMBOLS MUST BE EQUATED 
USING THE MEMORY LIMITS OF THE PROGRAM TO BE COPIED: 


we me we fee 


i ‘PST ° 
i “PND “ 


PROGRAM START ADDRESS (SEE SAMPLE PROGRAM). 
PROGRAM END ADDRESS (SEE SAMPLE PROGRAM}. 


PST= $0700 
PND= $1324 


FLEN= PND-PST+127/128#128 i ROUND UP TO MULTIPLE OF 128. 
+= $BO00 i; THIS PROGRAM’S ORIGIN. 
BOOTB LDX #$10 i USE IOCB #1. 


i FIRST OPEN THE CASSETTE FILE FOR WRITING. 


LDA #0PEN ; SET FOR DEVICE “OPEN.” 
STA ICCOM, X 

LDA #0PNOT i DIRECTION IS “OUTPUT. “ 
STA ICAX1, X 

LDA #$80 i; SELECT SHORT IRG. 

STA ICAXe2, X 

LDA #CFILE ; SET UP POINTER TO DEVICE NAME. 
STA ICBAL, X 

LDA #CFILE/256 

STA ICBAH, X 

JSR Cr1OvV ; ATTEMPT TO OPEN FILE. 

BMI CERR i ERROR. 


i NOW WRITE THE ENTIRE FILE AS ONE OPERATION. 
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LDA 
STA 


LDA 
STA 
LDA 
STA 


LDA 
STA 
LDA 
STA 


JSR 
BMI 


#PUTCHR 
ICCOM, X 


#PST 
ICBAL, X 
#PST/256 
ICBAH, X 


#F LEN 
ICBLL, X 
#FLEN/256 
ICBLH, X 


CIOVv 
CERR 


i 


i 


SET UP FOR “PUT CHARACTERS. “ 


POINT TO START OF APPLIC. PROG. 


SET UP # OF BYTES TO WRITE. 


WRITE ENTIRE FILE. 
ERROR. 


i NOW CLOSE THE FILE AFTER SUCCESSFUL WRITE. 


LDA 
STA 


JSR 
BMI 


BRK 
BRA 
. BYTE 
IS THE 
$BFF9 
RTS 
. WORD 
. BYTE 


. WORD 
. END 


#CLOSE 
ICCOM:, X 


CIOV 
CERR 


“G: *, CR 


CARTRIDGE 


BOOTB 
0,4 


INIT 


HEADER 


i 


oe UP FOR “Clouse.” 
CLOSE THE Ff iLE. 
ERROR. 

STOP WHEN DONE. 
STOP ON ERROR. 


FILE NAME. 


"A" CARTRIDGE. 
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11 ADVANCED TECHNIQUES AND APPLICATION NOTES 


This section presents information to use the capabilities of the OS 

and some of the hardware capabilites that aren’t directly available 

through the OS .and in fact, can be in direct conflict with parts of 
the OS. 


SOUND GENERATION 


The O05 uses the POKEY sound generation capabilities only in the I/0 
subsystem, for cassette FSK tone generation. and for the “noisy 
bus" option in SIO. 


Capabilities 


The hardware provides four independently programmable audio 
channels that are mixed and sent to the television set as part of 
the composite video signal. The POKEY registers shown below are all 
concerned with sound control (as described in the ATARI Home 
Computer Hardware Manual>. 


AUDCTL CB208] Audio control. 

AUDC1 f£B201] and AUDFI CD200] Channel i control. 
AUDC2 [fB203] and AUDF2 [D202] Channel 2 control. 
AUDCS f£B205] and AUDFS [D204] Channel 3 control. 
AUBDC4 f£B207] and AUDF4 [D206] Channel 4 control. 


Conflicts With OS 


There are two potential conflicts with the OS involving sound 
generation: 


) The OS can generate its own sounds and then turn off all sounds 
as part of I/0 operations to the cassette and the serial bus 
peripherals. 


oO The OS does not turn off sounds when you press CSYSTEM. RESET] or 
CBREAK]. If the sounds are to be turned off under those 
conditions, the controlling program must provide that capability. 
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SCREEN GRAPHICS 


Hardware Capabilities 


The hardware capabilities for screen presentations are quite 
versatile; the OS uses a very small amount of the capability 
provided. The means of extension, however, are non-triviali and 
making changes to a screen format while still utilizing the 
resident Display Handler will be difficult. See the ATARI Home 
Computer Hardware Manual for information regarding screen 
presentations. 


OS Capabilities 


The resident Display Handler arbitrarily supports 8 of the il 
possible full screen modes (11 of 14 modes if the GTIA chip is used 
in place of the CTIA}. The resident Display Handler allows for an 
optional “split-screen" text window of fixed size. The hardware 
allows for many more options than the Display Handler supports, as 
will be seen by reading the ATARI Home Computer Hardware 

Manual. 


Cursor Control 


You can control the Display Handler text and graphics cursors 
directly (see Section 5 and Appendix L. Bi-4}. 


Color Control 


You can alter the color register assignments that the Display 
Handler makes upon all OPEN commands (see Appendix L B7-& and 
elsewhere). Note that every system reset or Display Handler OPEN 
will reset the values back to the system default. 
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Alternate Character Sets 


Two character sets are available in screen text modes 1 and 2. The @ 
value stored in the data base variable CHBAS [(G2F4] selects the 

character set of interest to you. The default value of $E0 

provides capital (uppercase) letters. numbers and the punctuation 

characters corresponding to display codes $20 through $5F in 

Appendix E}. The alternate value of $E2 provides lowercase letters 

and the special character graphics set (corresponding to display 

codes $60 through $7F and $00 through $1F in Appendix E}. 


User-defined character sets can also be obtained for text modes O, 
i, and 2 by providing the character matrix definitions in RAM and 
setting CHBAS to point to those definitions. CHBAS always contains 
the most significant bits of the memory address of the start of the 
character definitions, as shown below: 


CHBAS H MSB ae Text mode O 


+—+ 
: MSB ix Text modes i and 2 
+—+ 


Figure ii-i User-Defined Character Set Bit Memory Addresses 


(X indicates an ignored address bit 
assumed to be O. } 
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Fach character is defined by an 8 x 8 bit matrix; the 
character ‘@’ is defined as shown below: 


e : 


Byte t-4+—-4-4—-4+-—4+—-4-4+—4+ 
POrO;ro:8:oid:ioiog: O 
Sede alee aioe aie sei aioe eke teas 
POrOri1~iLtiLiLtioiodi 1 
+ + HH Ft 
PCOrLi pti iorrsrLtioiost 
+H tH $F HH HHH 
COLL itioiriLridoiodst 
+t + tH HH Ht 
(Or LiLiGriLriLrioiost 
FH pH tH tH tt HH 
(Or L Lio iG:idisici 
5 cies alanis aheeie sien aeeiaaieniadiaee aieaeie 
CO1rOrLriz_iLtilioios 
+t — HH HH + 
(O1rOrOroidididid: 
+— + — tH HH 


wh OR ae Ben 


Figure ii-2 User Defined 8 x & Character Matrix Bit Table 


The storage for the character set involves eight consecutive 
bytes for each character with characters ordered consecutively by 
their internal code value (see the discussion in Appendix L 
relating to BSS}. 


Character for 


Character base ‘ 
i code $00 


8 bytes 


Character for 
code $0i 


increasing addresses 


Character for 
code #7E 


Character for 
code $7F 


Figure 11-3 Character Base Diagram 
PLAYER/MISSILE GRAPHICS 
The OS makes no use of the player/missile generation capability 


of the hardware. It can be used independently of the OS with no 
conflict. 
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Hardware Capabilities 


The hardware allows a number of independently moveable screen 
obyects of Limited width to be positioned and moved about the 
screen without affecting the “playfield” (bit-mapped graphics or 
character) data. Priority control allows the various objects to 
have a display precedence in case of conflict (overlap?. 


Conflicts With OS 


You must assure that the player/missile data is 

address~-aligned as required by PMBASE [D407]. You also must 

find a suitable free area that the OS guarantees to be free under 
all environments. 


READING GAME CONTROLLERS 


The OS reads the game controllers (shown below} as part of the 
stage 2 VBLANK process (see Appendix L Ji-9}: 


Joysticks/triggers 1-4. 

Paddle controllers/triggers 1-8. 
Driving controllers/triggers 1-4. 
Light pen/trigger 


In addition to these controllers, other information can be sensed 
or sent using the PIA chip to that the console connectors are 
interfaced. 


Keyboard Controller Sensing 


Data can be read from an ATARI keyboard controller connected to the 
first port. This program alters registers on a chip called a PIA. 

To set these back to the default values to do further I/0. hit 
CSYSTEM. RESET] or POKE PACTL, 60. If this program is to be loaded from 
diskette, use LOAD, not RUN and wait for the busy Light on the disk 
drive to go out. Do not execute the program before this light goes 
out, otherwise the diskette continues to spin. 


1 GRAPHICS 0 

2 PRINT : PRINT " KEYBOARD CONTROLLER DEMO" 

10 DIM ROW(3}), 1$(13), BUTTONS(1) 

30 GOSUB 4000 

40 FOR CNT=1 TO 4 

60 POSITION 2, CNT#2+5: PRINT "CONTROLLER # “i CNT; ": “; 
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70 NEXT CNT 


80 FOR CNT=1 TO 4: GOSUB 7000: POSITION 19, CNT+CNT+5: PRINT BUTTONS; 


>NEXT CNT 

120 GOTO 80 

6000 REM ## SET UP FOR CONTROLLERS ++ 

6010 PORTA=54016: PORTB=54017: PACTL=S4018: PBCTL=S4019 

6020 POKE PACTL, 48: POKE PORTA, 255: POKE PACTL, 52: POKE PORTA, 221 

6025 POKE PBCTL. 48: POKEPORTB, 255: POKE PBCTL, 52: POKE PORTE, 221 

6030 ROW(0)=238: ROW( 1} =221: ROW(2)=187: ROW(3)=119 

6040 [$=" 123456789#0#" 

6050 RETURN 

7O00 REM #+# RETURN BUTTONS WITH CHARACTER FOR BUTTON WHICH HAS 
BEEN PRESSED ON CONTROLLER CNT (1-4). #+# 

7OOL REM ## NOTE: A i WILL BE RETURNED IF NO CONTROLLER IS 
CONNECTED. ## 

7002 REM ## A SPACE WILL BE RETURNED IF THE CONTROLLER IS 
CONNECTED BUT NO KEY HAS BEEN PRESSED. #+# 

7003 PORT=PORTA: IF CNT>2 THEN PORT=PORTB 

7005 P=i1 

7008 PAOQ=CNT+CNT-2 

7010 FOR J=0 TO 3 

7020 POKE PORT, ROW( J} 

7030 FOR I=1i TO 10:NEXT I 

7050 IF PADDLE(PA0+1)>10 THEN P=J+J+J+2: GOTO 7090 

7060 IF PADDLE(PA0)>10 THEN P=J+J+J+3: GOTO 7090 

7070 IF STRIG(CNT-1i}=0 THEN P=J+J+J+4: GOTO 7090 

7O80 NEXT J 

709O BUTTONS=I14$(P, P} 

7095 RETURN 


Figure 11-4 Reading Data From an ATARI Keyboard Controller 
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The table below shows the variable/register values used for reading a 
keyboard controller from each of the four controller ports. 


Port 1 Port 2 Port 3 Port 4 
Salis slate sieeeta chanel steaks. chemi alana ateeie eniecalenien oeecke eee ateciecaieeia ahem aaa sheet aieaie eee atic a 
: PORT A } H ‘ : H 
idirectioni OF i: FO ‘ - { _ H 
ibits H { H { 
+--+ — 4-4 —$— 4 — 4-4-4 — $$ — HH HH tt 
; PORT B H ‘ ‘ { 
‘direction! _ { _ |. - OF ; FO H 
(bits H ‘ H { H 
S aie seas ates lente aie deed: chet cheeks checks ieee cee cee ee ee ee ee ee ee oo 
: Port A | FE.FD,! EF, DF : H { 
; Tow sel {| FB.F?7 : BF,.7F t - oe H 
i ect { H { { H 
ate ieee ieee aie eee ee ee Se Se ae Se Se Oe ee ee ee ee 
: Port B : H : FE, FD, | EF. DF, { 
i Tow se- { - H _ i FB,F?7 {| BF.7F ! 
: lect H H { H H 
Select deat ateeeiec alent clea steed chee aii cieecia ieee cies cee chee eee a Se Se ee Se 
(| Column 1LiPADDLi tPADDLS3S {PADDLS !{PADDL7 : 
t Sense H H i H { 
Faerie alaeeia sieaeie steele chanel cieeeie dic dees cee eet eee ieee eee i ce ieee ee Se Se ee 
i Column 2!PADDLO !PADDL2 ‘tPADDL4 ![{PADDL6 |: 
| Sense ; @ 
Sie. cieeeie Sheela sheeeie chee eee cite ieee eee aie cee eee ee eee es Se Se es oe See Se 
( Column BSISTRIGO :!STRIG1 [{STRIG2 {iSTRIGS | 
i: Sense H { H H H 
Secale aieeeia sina ieee ateecte aieecie chee lene cheek aac stent alanie aie ahenia diene eae tenia steele aie leiaaieaaie a 


Figure i1i-5 ATARI Keyboard Controller Variable/Register Value 
Table 


Front Panel Connectors as I/0 Ports 


The three pages that follow show how some of the pins in the front 
panel (game controller?) connectors can be used as general I/O pins. 


Hardware Information 


PIA (6520 / 6820} 
Out: TTL levels. i load 
: Eee TTL levels. i load For more information refer 
to 6520 chip manual. 
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Port A Circuit (typical): 


A 
6520 W—lyack 
a aa 


Male connector, FRONT view 
Seo ie Pin 8 = Ground 
Pin 7 = Vee 8tSv *) 


Port B Circuit (typical): 


+5 Note: SOmA maximum 


total external drain 
6520 Jyack on power supply allowed 


mes 


"Trigger" Port Circuit (typical): 


22Q 


CTIA Trig | Jack 
2 aps 


Software Information 


6520 PIA: (This also pertains to all of the following: #+#) 
Port A control (address D302) 


/ & 23. 4 22 2S 


see Write this into this register 
tg 


Port A Data/Data direction addres 
ing control 

0 Data Direction is at B3O0O 

1 data is at B3OC 


Port A data direction (address D300} 


Write this into this register. 


Data direction control 


for Port A 
1 = Qut 
O = In 
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Port A data (address DOOO) 
= 6 oS 4 8S a | EG 


B22232. 22225 Read or Write this register _ 


Jack 2 Jack 1 
Pin Numbers 


Port B Control (address DBDGOS:> 


jo fos [t]1 | xjolo 


6520 PIA: 
Port B Control (address D3OS) 
4 ees Se Se 


PY e-SEGEee &so3ee write this into this register 


Be B Data/Data direction 
addressing control 
D3C1 contains data 
direction 

$D301 contains 


0 


1 


Port B data direction (address D301} 
» See eo > ile meee ee eee 


Abe xe ee x |e write this into this register 
me Be Se data direction control for Port B 


1 = Out 
GO = In 


Port B data (address DSO) 


= &— 9 4 2S eS ee 


Fee Se BSS EAS 


4235914 423535 -4 
Ne ear aa! 


Jack 4 J ack 3 
Pin Numbers 


Four “Trigger” ports: DO1Q, DOLL, BOie, BOIS 
7. S23: 4.23 sa 3 


Fo} o| ao} o}o}ofo} x Read this port 
Trigger Value 


D010 = Port 1 Pin & 
DOIS = Port 4 pin & 
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Other Miscellaneous Software Information 
© i}. The OS sets up all PIA ports as inputs during 
initialization. 


2}. The OS usually reads the above once per television frame 
(during 


vertical-blank ) 


into RAM as follows: 


Data Base Name Address Data Pins S 
STICKO 0278 7 6-3 4° 3 SS 8 Jack 1, pins 4:3,2, 
roToloyolx| x|x]x if 10053, 7 
STICKI 0729 Jack 2, Pins 4,3,2,1 
STICK2 027A Jack 3, Pins 4,3,2, 1 
STICKS 0278 Jack 4 Pins 4,3,2, 1 
STRIGO 0284 Jack 1, Pin & 
\ ee ee ee, Se ae ee SE 

STRIGI 0285 O10] 0] 0] O] O] O| |vack 2, Pin 6 
STRIG2 0286 Jack 3. Pin & 
STRIGS 0287 Jack 4, Pin & 
PADDL i OerG 7 42-4... 4 23-2. iz 

Lhe bat ae ee) ee Jack 1, Pin 53 
PADDL3 0272 Jack 2. Pin 5 
PABDLS 0274 Jack 3. Pin 5 
PADDL? 0274 Jack 4, Pin 5 
PADDLO 0271 Jack 1, Pin 9 
PADDL2 0273 Jack 2, Pin 9 
PADDL4 0275 Jack 3. Pin 9 
PADDL 6&6 0277 Jack 4, Pin 9 


Figure 11-6 Using Front Panel Connectors As I/0 Ports: 


Function Tables 


Pin 


+ Pins 5 and 9 are read through the paddle controller circuitry 
a nominal value of 7 indicates that the pin is high (or floating) 
and a nominal value of 228 indicates that the pin is pulled low. 
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Appendix A -- CIO COMMAND BYTE VALUES 


The following hex values are known to be legitimate CIO commands. 


Most handlers: 


OPEN 

GET RECORD 

GET CHARACTERS 
PUT RECORD 

PUT CHARACTERS 
CLOSE 

GET STATUS 


Display Handler only: 


Se gt 
12 -- BRAW 


Diskette File Manager only: 
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RENAME 
DELETE 
FORMAT 
LOCK 
UNLOCK 
POINT 
NOTE 
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Appendix B -- CIO STATUS BYTE VALUES 


Shown below 


O1 


(OO1} 


(128) 
(129) 
(130) 
(131> 
(132) 
(133) 
(134} 
(135} 
(1363 
(137>} 
(138) 
C139) 
(140} 
(141 >} 
(142) 
(143> 
(144) 
(145) 
(146) 
(147) 


(160) 
(161) 
(162) 
(143) 
(164} 
(165) 
(166} 
(1673 
(166) 
(149) 
(170) 
C3732 


ate the known CIO STATUS BYTE values. 


OPERATION COMPLETE (NO ERRORS) 


CBREAK] KEY ABORT 

IOCB ALREADY IN USE (OPEN) 
NON-EXISTENT DEVICE 

OPENED FOR WRITE ONLY 

INVALID COMMAND 

DEVICE OR FILE NOT OPEN 

INVALID IOCB NUMBER (Y reg only} 
OPENED FOR READ ONLY 

END OF FILE 

TRUNCATED RECORD 

DEVICE TIMEOUT (DOESN’T RESPOND} 
DEVICE NAK 

SERIAL BUS INPUT FRAMING ERROR 
CURSOR out-of-range 

SERIAL BUS DATA FRAME OVERRUN ERROR 
SERIAL BUS DATA FRAME CHECKSUM ERROR 
DEVICE DONE ERROR 

BAD SCREEN MODE 

FUNCTION NOT SUPPORTED BY HANDLER 
INSUFFICIENT MEMORY FOR SCREEN MODE 


DISK DRIVE # ERROR 

TOO MANY OPEN DISK FILES 
DISK FULL 

FATAL DISK I/0 ERROR 
INTERNAL FILE # MISMATCH 
FILE NAME ERROR 

POINT DATA LENGTH ERROR 
FILE LOCKED 

COMMAND INVALID FOR DISK 
DIRECTORY FULL (64 FILES)? 
FILE NOT FOUND 

POINT INVALID 
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Appendix C -- SIO STATUS BYTE VALUES 


Shown below 
O01 (001) -- 


8A (138) -- 
8B (139) -- 
SC (140) -- 
GE (142) -- 
@F (143) -- 
90 (144) -- 
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are the known SIO STATUS BYTE hexadecimal values. 
OPERATION COMPLETE (NO ERRORS)? 


DEVICE TIMEOUT (DOESN’T RESPOND)? 
DEVICE NAK 

SERIAL BUS INPUT FRAMING ERROR 
SERIAL BUS DATA FRAME OVERRUN ERROR 
SERTAL BUS DATA FRAME CHECKSUM ERROR 
DEVICE DONE ERROR 
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Appendix D -- ATASCII CODES 


> ee 


NmnwrFrFmuuor @ad a 
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Appendix E -- BISPLAY CODES (ATASCII) 
YX 2X 4X 6X 8X 


BY 
G1 
G2 
G3 
G4 
g5 
06 
Q7 
G8 
g9 
GA 
QB 
YC 
gD 
QE 
OF 


OD HP rUrFoe a ho oaao eo GY 


AX CX EX e 
| 80-FF SHOW AS | ©@ 
THE INVERSE VIDEO 
CODES @9-7F | 
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@ 
A 
B 
G 
D 
E 
F 
G 
H 
i 3 
J 
K 
L 
M 
N 
O 


19 
fe: 
12 
Se 
14 
15 
16 
17 
18 
a9 
1A 
1B 
bs da 
1D 
1E 
iF 


Oo ON KD OF WN FH BW 


Dit ee eg | ee 


OOGOWSSCOSUOC OOO] SRD CCVSIRESOSCSSS 


ba Pe) -O§s < *& es ct OR QA 
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Appendix F -- KEYBOARD CODES (ATASCII) 


CTRL SHIFT & SHIFT LOWER 
LOWER 

OO t 20 20 <space> 21 40 @ 35 60°“; 
O1 & SF 21 i 1F 41 A SF 61 a 
Oe B 15 aa * 1E 42 8 15 62 »b 
03 C 12 23 #* 1A 43 c¢ i2 63 ¢ 
04 BD 3A 24 $$ 18 44 BD 3A 64 d 
OS & =e i go Bae 3 1D 45 E 2A 65 e 
0&6 F 38 26h 1B 46 F 38 656 f 
O07 G 3D of gs eo 47 ¢ 3B GF. ¢g 
08 H 39 ao 30 468 H 39 668 4h 
09 I OB 2? 3} 32 49 f OD 5&9 i 
CA J O1 oA # 07 4Q4 J O1 6A Jj 
OB KK 05 2B + O& 4B K O5 6B k 
Oc L 60 2C , 20 4C t 00 eG 4 
OD M 25 2D - OE 4D M 25 6D m 
OE N 2a on a2 4E N 23 6 
OF 0 08 ar 26 4F 0 0O8 6F oa 
10 P GCA a: 0 32 370 =P OA 7G 3 
11 Q 2F “| Sia iF $i: 2 —2F 71 oq 
12 R 28 < ~ 1E S52 OR O28 fa? 
is S SE ot 1A 53 S$ GE 73 =O 
14 2 2D 34 4 18 394 TT 2D 74 = ¢ 
15 U OB a0. 1D 272 Ve fa 6 6U 
14 V 10 36 & iB 54 V 10 76 
17 W 2E < ¥ er J i ~ ee, See I 77 ow 
18 K 14 so 6g Ho be [29 %X 126 78 x 
19 Y 2B 39 #69 30 ay YY. 2 i, Sees * 
1A zZ a oe 02 ~ |, er eee Fg 7A 2 
iB <esc> ic wo i OB SB C€ 20 7B i 
ic. “<p> OE wo <x 36 ow Ne O06 fet 
1D “<down> OF 3D = OF 5D J 22 7D <clear> 
1E (C “<left> O06 a > 7 ede, © ¥ y 7E <back> 
iF... “Cri ganstoe7 eS 26 or. EE 7F <tab> 
BO-9A /IN GCO-1A SF s<itab> 2C 
9B <return> and “3 0O0C,1A AO-FC /itN 20-7C 
9C stdel> 34 D> “2 1E 
9D stCinsert>37 FE “<del> 34 
FE ..“<Ctaeb> 2C FF “<insert>37 
“<clear> ::= st or “< 
<return> ::= <return> or s<treturn> or “<return> 
“esc > ::= <esc> or stesc> or ““escr> 
<space> ::= <space> or s<space> or ““space> 


Where: s as a prefix indicates CSHIFTI. 
"as a prefix indicates CCTRLI. 


/itN as a prefix indicates ATARI key inverse active. 
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Appendix G@ -- PRINTER CODES (ATASCITI)> 


Character set for "normal" mode printing: 


20 <space> 40 @ + ee 
ai- $ 4i A 61 a 
<7 42 8 62 »b 
23 # 43 C 53 =f 
24 $$ 44 BD 64 qd 
See 3 45 cE 65 e 
26 & 4& F 65 f 
ar. 47 G Gf yg 
28 48 4H 68 h 
avr) 49 iI ay 3 
2A 4A J 6A f 
2B + 4B K 6B k 
ry. sae 4c L ee | 
20 = 4D »M 6D m 
*. 4E WN 6 = 7 
ar 4F 0 ee > 
et eee 2 F rie eee 
< 5 See | =... @& ro Stee | 
Mc ee va Fk 72 Tf 
ce 73 § 73 ~=«6¢ 
34 4 34 #T 74 = =«6¢ 
Se ao 73 YU 
26 36. :<¥ 76° ¥ 
aS 27 #2W 77 ow 
se: & [6 xX fa 2 
37 = ~ 2 eee Y ds tes 
SA: SA Z 7A 2 
|: we. s fe  ¢< 
ae - , eee, fg a 
3D = a 7D } 
=. - + Pe 7 Spey 
ee a = 7F <space> 


Note: The following codes print differently than defined by 
the ATASCII definition. 


O00 through IF print blank. 

60 prints * instead of "diamond". 
7B prints {£ instead of "spade". 

7D prints } instead of “clear". 

7E prints ™~ instead of “backspace". 
7F prints blank instead of “tab". 
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Character set for “sideways" mode printing: 


40 @ 60 @ 
41 A 61 A 
42 8B 62 8 
43 C 63 C 
44 BD 64 BD 
45 €E 65 €E 
46 F 66° Ff 
47 G &7 G 
48 H 68 4H 
49 I 69. 3 
4A J 6A J 
4B K 6B K 
ee * oe 
4D M 4D M 
4E WN 6E WN 
4F 0 6F OO 
30 690 20 P 7a? 
< > See vi @Q 7. 6 
32 2 ve =R 72 R 
33 3 23 «6 aS 
34 4 294 +#*T 74 =#T 
< ~ ee ve GV 73 6 
34 4 76 V 7&6. -V 
< | ae 8 27 60W 77 #2W 
38 8 278 xX 78 X 
a7. 9 wy Y Fi ee 
SA: 2A Z 7m 
wef wo. A 7B 
3c 6 6¢< ~ . ae * y ae 
3D = ee i: es 
SE <up> 7E <up> 
‘| es a OF <left> 7F <left> 


Note: the following codes print differently than defined by 
the ATASCII definition. 


OO through 2F print blank. 

SE prints “up arrow" instead of 

OF prints “left arrow" instead of 

60 through 7F repeats 40 through SF instead of proper set. 
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Appendix H -- SCREEN MODE CHARACTERISTICS 


Mode Horiz. Vert. Vert. Colors Data Color Memory 
& Posit. W/O Sp W Sp Value Reg. Reqd. 
(splitd (full} 
O 40 24 oe 2 backgd. BAK 992 992 
OO-FF PF 2 
. PF 1i# 
1 20 24 20 2 backgd. BAK &74 672 


0O-3F PF O 
40-7F PF i 
BO-BF PF 2 
CO-FF PF 3 


2 20 12 10 5 backgd. BAK 424 420 
O00-3F PF O 
40-7F PF i 
S0-BF PF 2 
CO-FF PF 3 


BAK 434 432 
PF O 
PF 1 
PF 2 


BAK 694 696 
PF O 


“oO WhYd 


BAK 1174 1176 
PF O 


& 160 96 80 2 BAK 2174 2184 


m © LM © 
0 
TI 
fh 


7 160 96 BO 4 BAK 4190 4200 


8 320 192 160 2 Siie2 8138 


9 80 192 — 1 Note 2 8i3e 


10 80 192 ae 9 8138 


&HMe Oo 
a 
= 
OM © 
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2 Pr 1 
& PE 2 
Fé Pr S 
8 BAK 
9 BAK 
aa BAK 
B BAIA 
C PF O 
D Pe4 
. Pre 
a Pr 
11 86 192 —— 16 Note 3 8138 
Notes: 
* Uses color of PF 2, lum of PF 1. 
2 Uses color of BAK, lum of data value ($0-F). 
3 Uses color of data value ($0-F), lum of BAK. 
Pr s = Playfield color register x. 
PM x = Player/Missile Graphics color register x. 
BAK ::= Background color register (also known as PF 4). 


The default values for the color registers are shown below: 


é BAK = $00 
PFO = $28 

PFi = $CA 

PF2 = $94 

PF3 = $46 
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The form of a color register byte is shown below: 


7 6.5 4-4-2 1-0 © 
pp a pH HH 
i color + iva tO} 
+ pH — + 


Where: color (hex values) 


ro) 
CG 
3 


minimum luminance 


« 
% 


(increasing 


luminance } 


maximum luminance 


gray 

light orange 
orange 

red orange 
pink 

purple 
purple-blue 
blue 

blue 

light blue 
turquoise 
green-blue 
green 
yellow-green 
orange-green 
light orange 


NOQuhPQMe Oo 


TMOoOAmDPOONSUNFA HONK O 
Hununknduinbndbud t to a tt 
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Appendix I -- SERIAL BUS ID AND COMMAND SUMMARY 


Serial bus device IDs 
Floppy diskettes Di-D4 $31-34 


Printer Pi $40 
RS-232-C Ri-R4 $50-53 


Serial bus control codes 


ACK - $41 (‘A‘%) 
NAK - $4E (‘°N‘) 
COMPLETE - $43 (°C’%) 
ERR - $495 (‘EE’) 


Serial bus command codes 


READ - $52 (‘R’%) Disk 

WRITE - $57 (‘W’") Printer/Disk 
STATUS -~ $953 (’S°) Printer/Disk 
PUT(no check} - $50 (‘PP’) Disk 

FORMAT - $21 (’!°) Disk 

READ ADDRESS - $54 (°T%) 

READ SPIN ~ $51 (’‘Q’) Disk 

MOTOR ON - $55 (°’U") Disk 

VERIFY SECTOR - $56 (’V%) Disk 
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Appendix J —- ROM VECTORS 


The fixed address OS ROM JMP vectors are shown below; at each ; 
address is a JMP instruction to the indicated routine. 


Name Addr Reference Function 

DISKIV E450 + Diskette Handler initialization 
DSK INV E453 2. 4.2 Diskette Handler entry. 

CIOvV E454 2.2 CIO utility entry. 

SIOV E459 7. SIO utility entry. 

SETVBYV E4S5cC &.7.2 Set System Timers routine. 

SYSVBV E4SF 6.3 Stage 1 VBLANK entry. 

XITVBV E442 &.3 Exit VBLANK entry. 

SIOINV E465 + SIO utility initialization. 
SENDEV E468 % Send enable routine. 

INTINV E4&4B + Interrupt Handler initialization. 
CIOINV E46E + CIO utility initialization. 
BLKBDV E471 eae Blackboard mode entry. 

WARMSV E474 3 Warmstart (CSYSTEM. RESETIJ) entry. 
COLDSV E477 #: Coldstart (power-up?) entry. 
RBLOKV E47A % Cassette-read block entry. 

CSOPIV E47D + Cassette-OPEN input entry. 


* These vectors are for OS internal use only. 


The fixed address Floating Point Package ROM routine entry point © 
addresses are shown below; complete descriptions of the 
corresponding routines are provided in Section 8. 


AFP DSO0c ASCII to FP convert. 

FASC DSES FP to ASCII convert. 

IFP DSAA Integer to FP convert. 
FPI D9OD2 FP to integer convert. 
FADD DAGS FP add. 

FSUB DA4&O FP subtract. 

FMUL DADB FP multiply 

FDIV DB28 FP divide. 

LOG DECD FP base e logarithm. 
LOG10 DEDI FP base 10 logarithm. 

EXP DDBCO FP base e exponentiation. 
EXP10 DDBCC FP base 10 exponentiation. 
PLYEVL DB40 FP polynomial evaluation. 
ZFRO DA44 Clear FRO. 

ZFi DA4&S Clear FP number. 

FLDOR DDS? Load FP number. 

FLDOP DDSD Load FP number. 

FLDIR DBY8 Load FP number. 

FLDIP DBOC Load FP number. 

FSTOR DDA7 Store FP number. 

FSTOP DBAB Store FP number. 

FMOVE DBBG Move FP number. 
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The base addresses of the Handler vectors for the resident 
handlers are shown below: 


Screen Editor (EE) E400 
Display Handler (5) E410 
Keyboard Handler (K} E420 
Printer Handler (P) E430 
Cassette Handler (C} E440 


See Section 5 for the format of the entry for each Handler. 


The 6502 Computer interrupt vector values are shown below: 


Function Address Value 
NMI FFFA E7B4 
RESET FFAC E477 
IRQ FFFE E6FE 
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Appendix K -~- DEVICE CHARACTERISTICS 


This appendix describes the physical characteristics of the 
devices that interface to the ATARI 400 and ATARI 800 Home 
Computers. Where applicable, data capacity, data transfer 
rate, storage format, SIO interface, and cabling will be 
detailed. 


KEYBOARD 


The keyboard input rate is limited by the OS keyboard reading 
procedure to be 60 characters per second. The code for each key 

is shown in Table 5-4. The keyboard hardware has no buffering and is 
rate-limited by the debounce algorithm used. 


DISPLAY 


The television screen display generator has many capabilities 
that are not used by the Display Handler (as described in Section 
3S and shown in Appendix HH). There are additional display modes, 
obyect generators, hardware display scrolling, and many other 
features that are described in the ATARI Home Computer 

Hardware Manual. 


Since all display data is stored in RAM, the display data update 
rate is limited primarily by the software routines that generate 
and format the data and access the RAM. The generation of the 
display from the RAM is accomplished by the ANTIC and CTIA or GTIA 
chips using Direct Memory Access (DMA) to access the RAM data. 

The internal storage formats for display data for the various 


modes are detailed in the ATARI Home Computer Hardware 
Manual. 


ATARI 410 PROGRAM RECORDER 
The ATARI 410 Program Recorder has the following characteristics: 
DATA CAPACITY: 
100 characters per C-60 tape (unformatted). 
DATA TRANSFER RATES: 
# 600 Baud (60 characters per second? 
#Note: The OS has the ability to adyust to different tape speeds 


(447 —- 895 Baud?}. 
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STORAGE FORMAT: 


Tapes are recorded in 1/4 track stereo format at 1 7/8 inches per 
second. The tape can be recorded in both directions, where tracks 
1 and 2 are side A left and righti and tracks 3 and 4 are side B 
Tight and left (industry standard). On each side, the left 
channel (1 or 4) is used for audio and the right channel (2 and 
3) is used for digital information. 


The audio channel is recorded the normal way. The digital channel 
is recorded using the POKEY two-tone mode producing FSK data at 
up to 600 baud. The MARK frequency is S327 Hz and the SPACE 
frequency is 3995 Hz. The transmission of data is asynchronous 
byte serial as seen from the computer; POKEY reads or writes a 
bit serial FSK sequence for each byte, in the following order: 


1 start bit (SPACE> 

data bit O —+ 

data bit 1 H 

+— OQ = SPACE. 1 = MARK. 
data bit 6& | 
data bit 7 -+ 

1 stop bit (MARK} 


The only control the computer has over tape motion is motor 
start/stop; and this only if the PLAY button is pressed by the 

user. In order for recording to take place, the user must press 

both the REC and PLAY buttons on the cassette. The computer has 

no way to sense the position of these buttons, nor even if an 

ATARI 410 Program Recorder is cabled to the computer, so the user must 
be careful when using this device. 


SIO INTERFACE 


The cassette device utilizes portions of the serial bus hardware, 
but does not follow any of the protocol as defined in Section 9. 


ATARI S2OCLTM] 40-COLUMN IMPACT PRINTER 


The ATARI 820 Printer has the following characteristics: 


DATA CAPACITY: 


40 characters per line (normal printing} 
29 characters per line (sideways printing} 


DATA TRANSFER RATES: 
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Bus rate: xx characters per second. 
Print time (burst): xx characters per second. 
Print time (average): xx characters per second. & 


STORAGE FORMAT: 


3 7/8 inch wide paper. 
9X7 dot matrix, impact printing. 


Normal format -- 
40 characters per line. 
& lines per inch (vertical). 
12 characters per inch (horizontal). 


Sideways format -- 
2? characters per line. 
6& lines per inch (vertical). 
9 characters per inch (horizontal). 


SIO INTERFACE 


The controller serial bus IB is #40. 


The controller supports the following SIO commands (see Section 5 @ 
for more information regarding the Handler and Section 9 for a 
general discussion of bus commands}: 


GET STATUS 
The computer sends a command frame of the format shown below: 


Device ID = $40. 
Command byte = $53. 


auxiliary 1 = doesn’t matter. 
auxiliary 2 = doesn’t matter. 
Checksum = checksum of bytes above. 


The printer controller responds with a data frame of the format 
shown earlier in this appendix as part of the GET STATUS 
discussion. 


PRINT LINE 
The computer sends a command frame of the format shown below: 


Device ID = $40. 
Command byte = $57. 
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auxiliary 1 = doesn’t matter. 
auxiliary 2 = $4& for normal print or $53 for sideways. 
Checksum = checksum of bytes above. 


The computer sends a data frame of the format shown below: 
Leftmost character of line (column 1}. 
Next character of line (column 2}. 
Rightmost character of line (column 40 or 29}. 
Checksum byte. 
Note that the data frame size is variable, either 41 or 30 bytes 


in length. depending upon the print mode specified in the command 
frame. 


ATARI 810 DISK DRIVE 
The ATARI S1iOCTM] Disk Drive has the following characteristics: 


DATA CAPACITY: 


720 sectors of 128 bytes each (Disk Handler format). 
709 sectors of 125 data bytes each (Disk File Manager format). 


DATA TRANSFER RATES: 


Bus rate: 1920 characters per second. 
Seek time: 5.25 msec. per track + 10 to 210 msec. 
Rotational latency: 104 msec maximum (286 rpm). 


STORAGE FORMAT: 


5 1/4 inch diskette, soft sectored by the controller. 

40 tracks per diskette. 

18 sectors per track. 

128 bytes per sector. 

Controlled by National INS1771-1 formatter/controller chip. 

Sector sequence per track is: 18 1. 3% 3S 7 % 11, 12, 15, 
i7, 2, 4 & 8 10 12, 14, 16 


SIO INTERFACE 


The controller serial bus IDs range from $31 (for ‘Di’) to $34 


@ (for ‘B4a’}. 
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The controller supports the following SIO commands (see earlier 
in this Appendix for information about the Diskette Handler and 
Section 9 for a general discussion of bus commands}: gs 


GET STATUS 
The computer sends a command frame of the format shown below: 


Device ID = $31-34. 
Command byte = $53. 


auxiliary 1 = doesn’t matter. 
auxiliary 2 = doesn’t matter. 
Checksum = checksum of bytes above. 


The diskette controller responds with a data frame of the format 
shown earlier in this Appendix as part of the STATUS REQUEST 
discussion. 


PUT SECTOR (WITH VERIFY} 
The computer sends a command frame of the format shown below: 


Device ID = $31-34 
Command byte = $57. 


auxiliary 1 = low byte of sector number. 
auxiliary 2 = high byte of sector number (1-720}. 
Checksum = checksum of bytes above. 


The computer sends a data frame of the format shown below: 


1268 data bytes. 
Checksum byte. 


The diskette controller writes the frame data to the specified 
sector, then reads the sector and compares the content with the 
frame data. The COMPLETE byte value indicates the status of the 
operation. 


PUT SECTOR (NO VERIFY? 
The computer sends a command frame of the format shown below: 


Device ID = $31-34 

Command byte = $50. 

auxiliary 1 = low byte of sector number. 
auxiliary 2 = high byte of sector number (1-720). 
Checksum = checksum of bytes above. 


The computer sends a data frame of the format shown below: 
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128 data bytes. 
Checksum byte. 


The diskette controller writes the frame data to the specified 
sector, then sends a COMPLETE byte value that indicates the 
status of the operation. 


GET SECTOR 


The computer sends a command frame of the format shown below: 


Device ID = $31-34 

Command byte = $52. 

auxiliary 1 = low byte of sector number. 
auxiliary 2 = high byte of sector number (1-720). 
Checksum = checksum of bytes above. 


The diskette controller sends a data frame of the format shown below: 


128 data bytes. 
Checksum byte. 


FORMAT DISKETTE 
The computer sends a command frame of the format shown below: 


Device ID = #$31-34 

Command byte = $21. 

auxiliary i = doesn’t matter. 

auxiliary 2 = doesn’t matter. 

Checksum = checksum of bytes above. 


The diskette controller completely formats the diskette (generates 40 
tracks of 18 soft sectors per track with the data portion of each 
sector equal to all zeros) and then reads each sector to verify 

its integrity. A data frame of 128 bytes plus checksum is 

returned in that the sector numbers of all bad sectors (up to a 
maximum of 63 sectors) are contained, followed by two consecutive 
bytes of $FF. If there are no bad sectors on the diskette the first 

2 bytes of the data 
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Appendix L ~- OS DATA BASE VARIABLE FUNCTIONAL DESCRIPTIONS 


CENTRAL DATA BASE DESCRIPTION 


This appendix provides detailed information for those variables 
in the OS data base that can be altered by the user. Remaining 
variables are provided narrative descriptions. Information on the 
variables is presented in a multiple access scheme: Lookup 
tables are referenced to a common set of narratives, that is 
itself ordered by function. 


Variable descriptions are referenced by a label called a variable 
identifier (VIB) number. The label comprises a single letter 
followed by a number. A different letter is assigned for each 
major functional area being described, and the numbers are 
assigned sequentially within each functional area. Those 

Variables that are not considered to be of interest to any user 
are flagged with an asterisk (#) after their names. The data base 
lookup tables provided are: 


1. Functional grouping -- index to the function narrative and 
descriptions of variables, giving VID and variable name. 


2. Alphabetic list of names -- giving VID of description. 
3. Address ordered list -- giving VID of description. 


Item 1. the functional grouping index, starts on the next pagei 
the other two lookup tables are at the end of Appendix L. 
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FUNCTIONAL INDEX TO DATA BASE VARIABLE DESCRIPTIONS 


A. Memory configuration 
Al MEMLO 
A2 MEMTOP 
AS APPMHI 
A4 RAMTOP 
AS RAMSIZ 


B. Text/graphics screen 


Cursor control 
Bi CRSINH 
B2 ROWCRS, COLCRS 
B3 OLDROW, OLDCOL 
B4 TXTROW, TXTCOL 


Screen margins 
BS LMARGN 
B& RMARGN 


Color control 
B7 PCOLROG —- PCOLRS 
BS COLORO —- COLOR4 


Text scrolling 
BS SCRFLG# 


Attract mode 
BiG ATRACT 
Bii COLRSH+ 
Bi2 DRAMSK+# 


Tabbing 
Bi3S TABMAP 


Logical text lines 
Bi4 LOGMAPs 
BiS LOGCOL+s 


Split screen 
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Bi6é BOTSCR# 


FILL/DRAW function 
Bi7 FILDBAT 
Bi8 FILFLG# 
Bi9 NEW SROW+, NEWCOL+ 
B20 HOLD4+ 


Bei ROWINC#, COLINC# 
B22 DELTAR#, DELTAC# 
B23 COUNTR+# 

B24 ROWAC#, COLAC# 
B25 ENDPT+# 


Displaying control characters 


Escape (display following control char) 
B26 ESCFLG# 


Display control characters mode 
B27 DSPFLG 


Bit mapped graphics 
B28 DMASK# @ 
B29 SHFAMT+# 
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Internal working variables 


B30 
Boi 
B32 
B33 
B34 
B35 
B36 
B37 
B38 
B3? 
B40 
B4i 
B42 


HOLDi+x 
HOLD2+ 
HOLDS3+ 
TMPCHR+ 
DSTAT+# 
DINDE X 
SAVMSC 
OLDCHR+ 
OLDADR+ 
ADRESS+ 
MLTTMP / 


OPNTMP / TOADR* 


SAVADR /FRMADR+# 


BUFCNT+# 
BUFSTR*# 
SWPFLG+ 
INSDAT+# 
TMP ROW 
TMPLBT+# 
SUBTMP + 
TINDEX* 
BITMSK+# 
L_INBUF + 
TXTMSC 

TXTOLD* 


» TMPCOL+ 
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Internal character code conversion 
B54 ATACHR 
BSS CHAR 


C. Disk Handler 
Ci BUFADR+ 
C2 DSKTIM+# 


D. Cassette (part in SIO part in Handler} 


Baud rate determination 

Di CBAUDL+, CBAUDH+ 

D2 TIMFLG*# 

D3 TIMERI*#, TIMER2+ 

D4 ADDCOR# 

DS TEMP1i+ 

D& TEMPS+* 

D7 SAVIO# 


Cassette mode 
DS CASFLG# 


Cassette buffer 
DO CASBUF+# 
DiO BLIM+# 

Dii BPTR+ 


Internal working variables 
Di2 FEOF# 
Di3 FYYPE+ 
Di4 WMODE+ 
DiS FREQ+# 


E. Keyboard 


Key reading and debouncing 
El CHix 
E2 KEYDEL+ 
ES CH 
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Special functions 


Start/stop 
E4 SSFLAG 


CBREAK] 
ES BRAKKEY 


CSHIFTI/CCONTROLJ lock 
E& SHFLOK 
E?7 HOLDCH+ 


Autorepeat 
ES SRTIMR+# 


Inverse video 
ES INVFLG 


Console switches (CSELECTI, CSTARTI]., and COPTION]} 


F. Printer 
printer-buffer 
Fi PRNBUFs 


F2 PBUFSZ+# 
F3 PBPNT# 


Internal working variables 
F4 PTEMPs 
FS PTIMOT+ 


G. Central I/0 routine (CIO) 
User call parameters 


Gi IOCB 
G2 ICHID 
G3 ICDNO 
G4 ICCOM 
GS ICSTA 
G& ICBAL, ICBAH 
G7 ICPTL, ICPTH 
G8 ICBLL, ICBLH 
G? ICAX1, ICAX2 
GiO ICSPR 


Device status 
Gii DVSTAT 


device table 
Gi2 HATABS 
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CilO/Handler interface Parameters 


G13 ZIOCB (IOCBAS) & 
G14 ICHIDZ 
G15 ICDNOZ 
G16 ICCOMZ 
Gi7 ICSTAZ 
G18 ICBALZ, ICBALH 
G19 ICPTLZ, ICPTHZ 
G20 ICBLLZ, ICBLHZ 
G21 ICAX1Z, ICAX2Z 
G22 ICSPRZ (ICIDNO, CIOCHR) 


Internal working variables 
G23 ICCOMT+# 
G24 ICIDNO+# 
G25 CIOCHR+# 


H. Serial I/0 routine (SIO) 


User call parameters 


Hi DCB control block 
H2 BDEVIC 
H3 DUNIT 
H4 BCOMND 
HS DSTATS 
H&S DBUFLO, DBUFHI 
H7 DTIMLO 
HS8 DBYTLO, DBYTHI 
HY DAUX1, DAUX2 


Bus sound control 
H1iO SOUNDR 


Serial bus control 


Retry logic 
Hii CRETRY+# 
Hi2 DRETRY+# 


Checksum 
H1i3 CHKSUM+# 
Hi4 CHASNT+# 
H1i5 NOCKSM+ 
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Data buffering 


_ General buffer control 


Hié BUFRLO#, BUFRHI+ 
Hi7 BFENLO#, BFENHI+# 


Command frame output buffer 
H1i8 CDEVIC# 
Hi9 CCOMND+ 
H20 CAUX1#, CAUX2+# 


Receive/transmit data buffering 
H21 BUFRFL+* 
H22 RECVDN# 
H23 TEMP 
H24 XMTDON+ 


SIO timeout 
H25 TIMFLG# 
H26 CBIMV1+# 
H27 CDTMA1+# 


Internal working variables 
H28 STACKP+ 
H29 TSTAT# 
H30 ERRFLG+# 
H31 STATUS+# 
H32 SSKCTL+ 


J. ATARI controllers 


Joysticks 
Ji STICKO —- STICKS 
J2 STRIGO —- STRIGS 
Paddles 
J3 PADDLO —- PADDL7 
- PTRIG?7 


J4 PTRIGO 


Paddle controllers 
JB STICKO —- STICKS 
JO STRIGO —- STRIGS 


KA. Disk file manager 
Ai FMSZPG# 
K2 ZBUFP# 
K3 ZDRVA+ 
K4 ZSBA+# 
KS ERRNO+ 
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L. Disk utilities (DOS) 
Li DSKUTL+# 


M. Floating point package 
Mi FRO 
M2 FRE 
M3 FRI1i 
M4 FR2# 
MS FRX+# 
M& EEXP+ 
M7 NSIGN+# 
MS ESIGN+# 
M9 FCHRFLG+# 
M10 DIGRT# 
Mil CIX 
Mi2 INBUFF 
Mi3 ZTEMPi+ 
M14 ZTEMP4# 
M15 ZTEMP3+ 
M1i6é FLPTR 
Mi7 FPTR2+ 
M18 LBPRi+# 
M19? LBPR2* 
M20 LBUFF 
M21 PLYARG+ 
M22 FPSCR/FSCR# 
M23 FPSCRi/FSCRi+* 
M24 DEGFLG/RADFLG+# 


N. Power-Up and System Reset 
RAM sizing 
Ni RAMLO#, TRAMSZ+ 
N2 TSTBAT+ 


Diskette/cassette-boot 

N3 DOSINI 

N4 CKEY# 

N5 CASSBT# 

N& CASINI 

N7 BOOT ?+# 

NS DFLAGS+* 

N9 DBSECT# 

NiO BOOTADB+ 


Environmental control 
Nii COLDST 
Ni2 BOSVEC 
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CS RESETI 


eS Nis WARMST 


P. Interrupts 
Pi CRITIC 
P2 POKMSK 


System Timers 


Real-time clock 
P3 RTCLOK 


System Timer i 
P4 CDTMV1 
PS CDTMAI 


System Timer 2 
P& CDIMV2 
P7 CDTMA2 


System Timers 3-5 
P8 CDTMV3, CDTMV4, CDTMVS 
P? CDITMF3, CDTMF4, CDTMFS 


RAM-interrupt vectors 


@ NMI-interrupt vectors 
P10 VDSLST 
Pii VVBLKI 
Pie VVBLKD 


IRQ@-interrupt vectors 
Pi3 VIMIRG 
P14 VPRCED 
PiS VINTER 
Pié& VBREAK 
Pi7 VKEYBD 
Pi8 VSERIN 
P19 VSEROR 
P20 VSEROC 
P21 VTIMR1i, VTIMR2, VTIMR4 


Hardware register updates 
P22 SDMCTL 
P23 SDLSTL,. SDLSTH 
P24 GPRIOR 
P25 CHACT 
P2& CHBAS 
P27 PCOLR«x, COLOR x 
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Internal working variable 
P28 INTEMP+# 


R. User areas 
Ri (unlabeled } 
R2 USAREA 


This appendix contains descriptions of many of the data base 
variables; descriptions are included for all of the user- 
accessible variables and for some of the “internal"“ variables as 
well. Those variables that are not considered to be normally of 
interest to any user are flagged with an asterisk (#)} after their 
names: the other variables can be of interest to one or more of 
the following classes of users: 


End user. 

Game developer. 

Applications programmer. 
System utility writer. 
Language processor developer. 
Device Handler Writer. 


o0o0000 0 


Each variable is specified by its system equate file name 
followed by its address (in hex)? and the number of bytes reserved 
in the data base (in decimal), in the following form: 

«<name> (C<addressv, <size>] 
For example: 


MEMLO £O02E7, 2] 


Note that most word (2 byte) variables are ordered with the least 
Significant byte at the lower address. 
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A. MEMORY CONFIGURATION 


See Section 4 for a general discussion of memory dynamics and 
section 7 for details of system initialization. 


Al MEMLO CO2E7,2] -- User-free memory low address 


MEMLO contains the address of the first location in the free 
memory region. The value is established by the OS during power-up 


and system reset initialization and is never altered by the OS 
thereafter. 


A2 MEMTOP CO2ES, 2] -- User-free memory high address 


MEMTOP contains the address of the first non-useable memory 
location above the free memory region. The value is established 
by the OS during power-up and system reset initializationi and 
then is re-established whenever the display is opened, based upon 
the requirements of the selected graphics mode. 


AS APPMHI COOOE, 2] -- User-free memory screen lower Limit 

APPMHI is a user-controlled variable that contains the address 
within the free memory region below which the Display Handler cannot 
go in setting up a display screen. This variable is 

initialized to zero by the OS at power-up. 

A4 RAMTOP# [006A.1] -- Display Handler top of RAM address (MSB? 
RAMTOP permanently retains the RAM top address that was contained 

in TRAMSZ (as described in Ni? for the Display Handler’s use. The 
value is set up as part of Handler initialization. 


AS RAMSIZ CO2E4,11] —-- Top of RAM address (MSB only?) 


RAMSIZ permanently retains the RAM top address that was contained 
in TRAMSZ (as described in N1>?. 
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B. TEXT/GRAPHICS SCREEN 


See Section S for a discussion of the text and graphics screens & 
and their Handlers. 


Cursor Control 


For the text screen and split-screen text window there is a 
visible cursor on the screen which shows the position of the next 
input or output operation. The cursor is represented by inversing 
the video of the character upon which it resides; but the cursor 
can be made invisible, at the user’s option. The graphics screen 
always has an invisible cursor. 


The cursor position is sensed by examining data base variables 
and can be moved by altering those same variables: in addition, 
when using the Screen Editor, there are cursor movement control 
codes that can be sent as data (as explained in Section 5). 


Bi CRSINH (O02F0C,1] -- Cursor display inhibit flag 
When CRSINH is zero, all outputs to the text screen will be 


followed by a visible cursor (inversed character); and when 
CRSINH is nonzero, no visible cursor will be generated. 


CRSINH is set to zero by power-up, the CSYSTEM. RESET] or [BREAK] keys @ 
or an OPEN command to the Display Handler or Screen Editor. 


Note that altering CRSINH does not cause the visible cursor to 
change states until the next output to the screen: if an 
immediate change to the cursor state is desired, without altering 
the screen data, follow the CRSINH change with the output of 
CURSOR UP, CURSOR DOWN. or some other innocuous sequence. 


B2 ROWCRS £0054,1] and COLCRS (C0055, 2] -- Current cursor 
position 


ROWCRS and COLCRS define the cursor location (row and column, 
respectively) for the next data element to be read from or 
written to the main screen segment. When in split-screen mode, 
the variables TXTROW and TXTCOL define the cursor for the text 
window at the bottom of the screen as explained in B4 below. 


The row and column numbering start with the value zero, and 
increase in increments of one to the number of rows or columns minus 
i; with the upper left corner of the screen being the origin (0,0). 


ROWCRS is a single-byte variable with a maximum allowable value 
of 191 (screen modes 8-11); COLCRS is a @-byte variable with a 
maximum allowable value of 319 (screen mode 8}. 
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B3 OLDROW [O00SA.11] and OLDCOL (CO0OSB,2] -- Prior cursor position 


OLDROW and OLDCOL are updated from ROWCRS and COLCRS before every 
operation. The variables are used only for the DRAW and FILL 
operations. 


B4 TXTROW €0290,1] and TXTCOL (CO291,2] -- Split-screen text cursor 
position 


TXTROW and TXTCOL define the cursor location (row and column, 
respectively) for the next data element to be read from or 
written to the split-screen text window. 


The row and column numbering start with the value zero, and 
increase in increments of one to 3 and 39, respectively; with the 
upper left corner of the split-screen text window being the origin 
(0,0). 


Screen Margins 


The text screen and split-screen text window have user-alterable 
left and right margins that define the normal domain of the text 
cursor. 


BS LMARGN (€00S52.1] -- Text column left margin 


LMARGN contains the column number (0-39) of the text screen left 
margin: the text cursor will remain on or to the right of the 
left margin as a result of all operations, unless the cursor 
column variable is directly updated by the user (see B2 and B4 
above}. The default value for LMARGN is 2 and is established upon 
power-up or system reset. 


B& RMARGN £0053,1] -- Text column right margin 


RMARGN contains the column number (0-39) of the text screen right 
margin: the text cursor will remain on or to the left of the 
right margin as a result of all operations, unless the cursor 
column variable is directly updated by the user (see B2 and B4 
above). The default value for RMARGN is 39 and is established 
upon power-up or system reset. 
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Color Control 


As part of the stage 2 VBLANK process (see Section 6), the values of 
nine data base variables are stored in corresponding hardware 

color control registers. The color registers are divided into two 
groups: the player/missile colors and the playfield colors. The 
playfield color registers are utilized by the different screen modes 
as shown in Appendix H. The player/missile color registers are not 
used by the standard OS. 


B7 PCOLRO —- PCOLRS [02C0,4] -- Player/missile graphics colors 


Each color variable is stored in the corresponding hardware 
register as shown below: 


PCOLRO £02C0] 
PCOLR1 (02Ci] 
PCOLR2 (02C2] 
PCOLRS £02C3] 


COLPMO [D012] 
COLPM1 (CDO13] 
COLPM2 [D014] 
COLPMS (CDO1S] 


Each color variable has the format shown below: 


76434321 0 


See Appendix H for information regarding the color and luminance 
field values. 


BS COLORO —- COLOR4 (02C5,.5] -- Playfield colors 


Each color variable is stored in the corresponding hardware 
register as shown below: 


COLORO (02C4] COLPFO [D016] 
COLOR1 [(02C5] COLPFi CDO17] 
COLOR2 (02C6] COLPF2 (CDO18] 
COLORS (62C7] COLPFS3 (CDO19] 
COLOR4 £02C8] COLBK [CDO1A] 


Each color variable has the format shown below: 


7634321 0 


See Appendix H for information regarding the color and luminance 
field values. 
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Text Scrolling 


The text screen or split-screen text window “scrolls" upward 
whenever one of the two conditions shown below occurs: 


a) A text line at the bottom row of the screen extends past the 
Tight margin. 


o A text line at the bottom row of the screen is terminated by 
an EOL. 


Scrolling has the effect of removing the entire logical line that 
starts at the top of the screen and then moving all subsequent 
lines upward to fill in the void. The cursor will also move 
upward if the logical line deleted exceeds one physical line. 


BO SCRFLG# CO2BB,.1] -- Scroll flag 


SCRFLG is a working variable that counts the number of physical 
lines minus 1 that were deleted from the top of the screeni 


since a logical line ranges in size from i to 3, SCRFLG ranges 
from © to 2. 


Attract Mode 


Attract mode is a mechanism that protects the television screen 
from having patterns “burned into" the phosphors due to a fixed 
display being left on the screen for extended periods of time. 
When the computer is left unattended for more than 9% minutes, the 
color intensities are limited to SO percent of maximum and the 
hues are continually varied every &.3 seconds. Pressing any 
keyboard data key will be sufficient to remove the attract mode 
for 9 more minutes. 


As part of the stage 2 VBLANK process, the color registers from 
the data base are sent to the corresponding hardware color 
registers: before they are sent. they undergo the following 
transformation: 


hardware register = database variable XOR COLRSH AND DRAMSK 


Normally COLRSH = $00 and DRKMSK = $FE. thus making the above 
calculation a null operation; however, once attract mode becomes 
active, COLRSH = the content of RTCLOK+1 and DRAMSK = $F6é. that 
has the effect of modifying all of the colors and keeping their 
luminance always below the SO percent level. 


Since RTCLOK+1 is incremented every 256/60 of a second and 
since the least significant bit of COLRSH is of no consequence, a 
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color/lum change will be effected every 8.3 seconds (512/60). 


BiO ATRACT (004D.,11] -- Attract mode timer and flag 


ATRACT is the timer (and flag) that controls the initiation and 
termination of attract mode. Whenever a keyboard key is pressed, 
the keyboard IRQ@ service routine sets ATRACT to zero, thus 
terminating attract modei the CBREAK] key logic behaves 
accordingly. As part of the stage i VBLANK process, ATRACT is 
incremented every 4 secondsi if the value exceeds 127 (after ? 
minutes without keyboard activity). the value of ATRACT will 

be set to $FE and will retain that value until attract mode is 
terminated. 


Since the attract mode is prevented and terminated by the OS 
based only upon keyboard activity, some users can want to reset 
ATRACT based upon Atari-controller event detection, 
user~-controlled Serial I/O bus activity or any other signs of 
life. 


Bilt COLRSH* COO4F,1] -- Color shift mask 


COLRSH has the value $00 when attract mode is inactive, thus 
effecting no change to the screen colorsi when attract mode is 
active, COLRSH contains the current value of the timer variable 
middle digit (RTCLOK+1>. 


Bi2 DRAMSKs+ (C004E,13 -- Dark (luminance) mask 


DRAMSK has the value $FE when attract mode is inactive, which does not 
alter the luminance: and has the value $F6& when attract mode 

is active, which forces the most significant bit of the luminance 
field to zero, thus guaranteeing that the luminance will never 

exceed SO percent. 


Tabbing 

See Section 5S for a discussion of the use of tabs in conjunction 
with the Screen Editor. 

Bis TABMAP [02A3,15] -- Tab stop setting map 

The tab settings are retained in a 15-byte (120 bit) map. where a 


bit value of i indicates a tab setting: the diagram below shows 
the mapping of the individual bits to tab positions. 
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Whenever the Display Handler or Screen Editor is opened. this map 
is initialized to contain the value of $01 in every byte. thus 
providing the default tab stops at 7, 15, 23, etc. 


Logical Text Lines 


The text screen is invisibly divided into logical lines of text, 
each comprising from one to three physical lines of text. The 
screen is initialized to 24 logical lines of one physical line 
each: but data entry and/or data insertion can increase the size 
of a logical line to two or three physical lines. 


B14 LOGMAP# CO2B2. 4] -- Logical line starting row map 


The beginning physical line number for each logical line on the 
screen is retained in a four byte (32 bit} map. where a bit value 
of one indicates the start of a logical linei the diagram below 
shows the mapping of the individual bits to physical line (row? 
numbers. 
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The map bits are all set to 1 whenever the text screen is 
opened or cleared. From that point, the map is updated as 
@ logical lines are entered, edited and deleted from the screen. 
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BiS LOGCOL# £0063,11] -- Cursor/logical line column number 


LOGCOL contains the logical-line column number for the current 
cursor position: note that a logical line can comprise up to 
three physical lines. This variable is for the internal use of 
the Display Handler. 


Split Screen 


The Display Handler and Screen Editor together support the 

operation of a split-screen mode (see Section 5) in which the main 
portion of the screen is in one of the graphics modes and is 
controlled by the Display Handler, and there are 4 physical lines in 
the text window at the bottom of the screen which is controlled by the 
Screen Editor. 


Bi6 BOTSCR# CO2@BF,1]3 -- Text screen lines count 
BOTSCR contains the number of lines of text for the current 
screen: 24 for mode O or 4 for a split-screen mode. The Handler 


also uses this variable as an indication of the split-screen 
statusi tests are made for the specific values 4 and 24. 


DRAW/FILL Function 


The DRAW function line drawing algorithm is shown below 
translated to the PASCAL language from assembly language. 


NEWROW := ROWCRS: NEWCOL := COLCRS; 

DELTAR := ABS (NEWROW-OLDROW); 

ROWINC := SIGN (NEWROW-OLDROW);: f£ +1 or -1 } 
DELTAC := ABS (NEWCOL-OLDCOL); 

COLINC := SIGN (NEWCOL-OLDCOL); <€ +1 or -1 } 


ROWAC := 0; COLAC := @G; 
ROWCRS := OLDROW; COLCRS := OLDCOL; 


COUNTR := MAX (DBELTAC, DELTAR);: 
ENDPT := COUNTR: 
IF COUNTR = DELTAC 
THEN ROWAC ENDPT DIV 2 
ELSE COLAC ENDPT DIV 2; 


WHILE COUNTR > O DO 
BEGIN 
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ROWAC := ROWAC + DELTAR; 
IF ROWAC >= ENDPT 


THEN 
BEGIN 
ROWAC := ROWAC —- ENDPT; 
ROWCRS := ROWCRS + ROWINC 
END; 


COLAC := COLAC + DELTAC; 
IF COLAC >= ENDPT 


THEN 
BEGIN 
COLAC := COLAC —- ENDPT; 
COLCRS := COLCRS + COLINC 
END; 


PLOT _POINT; € point defined by ROWCRS and COLCRS } 
IF FILFLG <> O THEN FILL_LINE; 
COUNTR := COUNTR - 1 


END; 


The FILL function algorithm (FILL_LINE above} is described briefly in 
Section 5. 


B17 FILDAT CO2FD,1] -- Fill data 


FILLDAT contains the fill region data value as part of the calling 
sequence for a FILL command as described in Section 5. 


Bi8 FILFLG# (CO2B7,1] -- Fill flag 


FILFLG indicates to the shared code within the Display Handler 
whether the current operation is FILL (FILFLG <> 0} or DRAW 
(FILFLG = O}. 


Bi9 NEWROW+ (£0060,1] and NEWCOL# £0061,2] -- Destination point 
NEWROW and NEWCOL are initialized to the values in ROWCRS and 
COLCRS. which represent the destination endpoint of the DRAW/FILL 


command. This is done so that ROWCRS and COLCRS can be altered 
during the performance of the command. 


B20 HOLD4* CO2BC,11 -- Temporary storage 
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HOLD4 is used to save and restore the value in ATACHR during the 
FILL processi ATACHR is temporarily set to the value in FILDAT to 
accomplish the filling portion of the command. 


B21 ROWINC#® (£0079,1] and COLINC# (€0074,13 -- Row/column 
increment/decrement 


ROWINC and COLINC are the row and column increment valuesi they 
are each set to +1 or -1 to control the basic direction of line 
drawing. ROWINC and COLINC represent the signs of NEWROW -— 
ROWCRS and NEWCOL —- COLCRS, respectively. 


B22 DELTAR# (£0076.1] and DELTAC# £0077,2] -- Belta row and delta 
column 


DELTAR and DELTAC contain the absolute values of NEWROW — ROWCRS 
and NEWCOL - COLCRS., respectively: together with ROWINC and 
COLINC, they define the slope of the line to be drawn. 


B23 COUNTR# (C007E,2])] -- Draw iteration count 


COUNTR initially contains the larger of DELTAR and DELTAC., that 
is the number of iterations required to generate the desired 
line. COUNTR is then decremented after every point on the line is 
plotted, until it reaches a value of zero. 


B24 ROWAC# £0070,2] and COLAC# (£0072. 2] -- Accumulators 


ROWAC and COLAC are working accumulators that control the row-and 
column-point plotting and increment (or decrement? function. 


B25 ENDPT# £€0074,2] -- Line length 


ENDPT contains the larger of DELTAR and DELTAC. and is used in 
conyunction with ROWAC/COLAC and DELTAR/DELTAC to control the 
plotting of line points. 


Displaying Control Characters 


Often it is useful to have ATASCII control codes (such as CLEAR, 
CURSOR UP, etc). displayed in their graphic forms instead of 
having them perform their control function. This display 
capability is provided in two forms when outputting to the Screen 
Editor: 1) a data content form in which a special character (ESC} 
precedes each control character to be displayed and 2) a mode 
control form. 
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Escape (Display Following Control Character} 


Whenever an ESC character is detected by the Screen Editor, the 
next character following this code is displayed as data, even if 
it would normally be treated as a control code: the EOL code is 
the sole exception. It is always treated as a control code. The 
sequence ESC ESC will cause the second ESC character to be 
displayed. 


B26 ESCFLG# CO2A2,1] -- Escape flag 


ESCFLG is used by the Screen Editor to control the escape 
sequence function: the flag is set (to $80) by the detection of 
an ESC character ($1B) in the data stream and is reset (to 0} 
following the output of the next character. 


Display Control Characters Mode 


When it is desired to display ATASCII control codes other than 
EOL in their graphics form, but not have an ESC character 
associated with each control code, a display mode can be 
established by setting a flag in the data base. This capability 
is used by language processors when displaying high-level 
language statements, that can contain control codes as data 
elements. 


B27 DSPFLG CO2FE,1] -- Display control characters flag 


When DSPFLG is nonzero, ATASCII control codes other than EOL are 
treated as data and displayed on the screen when output to the 
Screen Editor. When DSPFLG is zero, ATASCII control codes are 
processed normally. 


DSPFLG is set to zero by Power-up and (CSYSTEM. RESET]. 


Bit-Mapped Graphics 


A number of temporary variables are used by the Display Handler 
when handling data elements (pixels) going to or from the screen: 
of interest here are those variables that are used to control the 
packing and unpacking of graphics data, where a memory byte 
typically contains more than one data element (for example, 
screen mode 8 contains 8 pixels per memory byte>. 


B28 DMASK# (CO2A0,1] -- Pixel location mask 
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DMASK is a mask that contains zeros for all bits that do not 
correspond to the specific pixel to be operated upon, and 
i’s for all bits that do correspond. DMASK can contain @ 
the values shown below in binary notation: 
11111111 -- screen modes i and 2; one pixel per byte. 


11110000 -- screen modes 7-11; two pixels per byte. 
OOOCO1111i 


1100000CG -- screen modes 3, 5S and 7i four pixels per byte. 
00110000 
00001100 
00000011 


10000000 -- screen modes 4, 6 and 8 eight pixels per byte. 
01000000 


000000106 

00000001 
B29 SHFAMT# COO46F,1] -- Pixel yjgustification 
SHFAMT indicates the amount to shift the right-justified pixel 
data on output, or the amount to shift the input data to right 


justify it on input. The value is always the same as for DMASK 
prior to the justification process. @ 


Internal Working Variables 

B30 HOLD1I# (€0051.11] -- Temporary storage 

B31 HOLD2+ CO29F,1] -- Temporary storage 

B32 HOLDS3S# £029D,1] -- Temporary storage 

B33 TMPCHR# £0050,1] -- Temporary storage 

B34 DSTAT# €004C,1] -- Display status 

B35 DINDEX £0057,11] -- Display mode 

DINDEX contains the current screen mode obtained from the low 
order four bits of the most recent OPEN AUXi byte. 

B36 SAVMSC (€0058,2] -- Screen Memory Address 

SAVMSC contains the lowest address of the screen data region: the 


data at that address is displayed at the upper left corner of the 
screen. ®@ 
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B37 OLDCHR# (€CCS5D,1] -- Cursor character save/restore 


OLDCHR retains the value of the character under the visible text 
cursor; this variable is used to restore the original character 
Value when the cursor is moved. 


B38 OLBDADR# COOSE,2] -—- Cursor memory address 


OLDADR retains the memory address of the current visible text 
cursor location: this variable is used in conjunction with OLDCHR 


(B37) to restore the original character value when the cursor is 
moved. 


B39 ADRESS# (0064,2] -- Temporary storage 

B40 MLTTMP/OPNTMP/TOADR# (0066.2) -- Temporary storage 

B4i SAVADR/FRMADR# £0068,2] -- Temporary storage 

B42 BUFCNT# (CO06B,1] -- Screen Editor current logical line size 
B43 BUFSTR*# (COO6C,2] -- Temporary storage 


B44 SWPFLG# (€007B,1] -- Split-screen cursor control 


In split-screen mode, the graphics cursor data and the text 
window cursor data are frequently swapped as shown below in order 
to get the variables associated with the region being accessed 
into the ROWCRS-OLDADR variables. 


ROWCRS B2 ------- TXTROW B4 
COLCRS B2 ------- TXTCOL B4 
DINDEX B35 ------ TINDEX B49 
SAVMSC B36 ------ TXTMSC B52 
OLDROW B3 ------- TXTOLD B53 
OLDCOL B3 ------- ; : 
OLDCHR B37 ------ ; ‘ 
OLDADR B38 ------ " ‘ 


SWPFLG is used to keep track of what data set is currently in the 
ROWCRS-OLDADR region; SWPFLG is equal to SFF when split-screen 
text window cursor data is in the main region. otherwise SWPFLG 
is equal to O. 


B45 INSDAT# (€007D,1] -- Temporary storage 
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B46 TMPROW# CO2BS,1] and TMPCOL# (CO2B9,2] -- Temporary storage 


B47  TMPLBT# €O2A1,1] -- Temporary storage 
B46 SUBTMP+ (CO29E,1] -- Temporary storage 


B49 TINDEX# €0293,1] -- Split screen text window screen mode 
TINDEX is the split-screen text window equivalent of DINDEX and is 
always equal to zero when SWPFLG is equal to zero (see B44). 


BSO BITMSK# COO6E,1] -- Temporary storage 


BS1 LINBUF# £0247,40] -- Physical line buffer 

LINBUF is used to temporarily buffer one physical line of text 

when the Screen Editor is moving screen data. 

BS2 TXTMSC (0294,2] -- Split screen memory address 

TXTMSC is the split-screen text window version of SAVMSC (B36). @ 


See B44 for more information. 


BSS TXTOLD# £0296.6] -- Split screen cursor data 


See B44 for more information. 


Internal Character Code Conversion 


Two variables are used to retain the current character being 
processed (for both reading and writing): ATACHR contains the 
value passed to or from CIO, and CHAR contains the internal code 
corresponding to the value in ATACHR. Because the hardware does 
not interpret ATASCII characters directly, the transformations 
shown below are applied to all text data read and written: 


ATASCII INTERNAL 
CODE CODE 
O0O-1F 40-SF 
20-3F O0-1F 
40-SF 20-SF 
60-7F 60-7F 
80-9F CO-DF 
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AO-BF 80-9F 
CO-DF AO-BF 
© EO-FF EO-FF 


See P26 for more information. 


BS4 ATACHR (CO2FB,.1] -- Last ATASCII character or plot point 
ATACHR contains the ATASCII value for the most recent character 
read or written, or the value of the graphics point. This 
variable can also be considered to be a parameter of the 
FILL/DRAW commands, as the value in ATACHR will determine the 
line color when a DRAW or FILL is performed. 


BSS CHAR# (CO2FA,1] -- Internal character code 


CHAR contains the internal code value for the most recent 
character read or written. 


C. DISKETTE HANDLER 


See Section 5S for a discussion of the resident Diskette Handler. 


Ci BUFADR# [0015.2] -- Data buffer pointer 


BUFADR acts as temporary page zero pointer to the current 
diskette buffer. 


C2 DSKTIM# (C0246. 1] -- Disk format operation timeout time 


DSKTIM contains the timeout value for SIO calling sequence 

variable DTIMLO (see Section 9). DSKTIM is set to 160 (which 
represents a 17i-second timeout) at initialization time, and is 
updated after each diskette status request operation. It contains the 
value returned in the third byte of the status frame (see Section 

9}. Note that all diskette operations other than format have a 

fixed (7) second timeout, established by the Diskette Handler. 


D. CASSETTE 


See Section 5 for a general description of the Cassette Handler. The 
cassette uses the Serial I/0 bus hardware, but does not conform with 
the Serial I/O bus protocol as defined in Section 9. Hence, the Serial 
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I/O utility (SIO) has cassette specific code within it. Some variables 
in this subsection are utilized by SIO and some by the Cassette 
Handler. 


Baud Rate Determination 


The input baud rate is assumed to be a nominal 600 baud, but will 
be adjusted, if necessary, by the SIO routine to account for 
drive-motor variations, stretched tape, etc. The beginning of 
every cassette record contains a pattern of alternating 1’s and 
zeros that is used solely for speed correction: by measuring the 
time to read a fixed number of bits. the true-receive baud rate 
is determined and the hardware adyusted accordingly. Input baud 
rates ranging from 318 to 1407 baud can theoretically be handled 
using this technique. 


The input baud rate is adyusted by setting the POKEY counter that 
controls the bit sampling period. 


Di CBAUDL# CO2EE,1] and CBAUDH* CO2ZEF,1] -- Cassette baud rate 


Initialized to OSCC hex. which represents a nominal 600 baud. 
After baud rate calculation, these variables will contain POKEY 
counter values for the corrected baud rate. 


D2 TIMFLG# (0317,11 -- Baud rate determination timeout flag 


TIMFLG is used by SIO to timeout an unsuccessful baud rate 
determination. The flag is initially set to 1, and if it attains a 
value of zero (after 2 seconds) before the first byte of the cassette 
record has been read. the operation will be aborted. See also H24. 


DS TIMER1I# CO30C,2] and TIMER2+# £(0310,2] -- Baud rate timers 


These timers contain reference times for the beginning and end of 
the fixed bit pattern receive period. The first byte of each 
timer contains the then current vertical line counter value read 
from ANTIC, and the second byte of each timer contains the then 
current value of the least significant byte of the O05 real time 
clock (RTCLOK+2)>. 


The difference between the timers is converted to raster pair 


counts and is then used to perform a table lookup with 
interpolation to determine the new values for CBAUDL and CBAUDH. 


D4 ADDCOR# COSOE, 1] -- Interpolation adjustment variable 
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ADDCOR is a temporary variable used for the interpolation 
calculation of the above computation. 


DS TEMP1# CO3i2,2] -- Temporary storage 


D&é TEMPS* £C0315,1] -- Temporary storage 


D7 SAVIO# £0316,1] -- Serial in data detect 


SAVIO is used to retain the state of SKSTAT CD20F] bit 4 (serial 
data indi it is used to detect (and is updated after) every bit 


arrival. 


Cassette Mode 


DS CASFLG# COSOF,1] -- Cassette I/0 flag 


CASFLG is used internally by SIO to control the program flow 
through shared code. A value of zero indicates that the current 
operation is a standard Serial I/O bus operation, and a nonzero 
value indicates a cassette operation. 


Cassette Buffer 


DO CASBUF# COSFD, 131] -- Cassette record buffer 


CASBUF is the 
and unpacking 
cassette-boot 
in the buffer 


buffer used by the Cassette Handler for the packing 
of cassette-record data, and by the initialization 
logic. The format for the standard cassette record 
is shown below: 


76549321 0 
tot te —$— 4-4-4 


(01010101 CASBUF+0 

= ciele leat denis seks dteads ale Seema 
(O1010i10ii1i +1 
Se ee ee ee ee ene ee ea 

i control byte : +2 
+—-+—+—4+-4+-4-4-4-4+ 

H 128 : +3 

= data = 

t bytes i +130 
tat ba tt — tt + 


See Section 5S for an explanation of the standard cassette-record 


e format. 
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DiO BLIM# €028A.1] -- Cassette record data size 


BLIM contains the count of the number of data bytes in the 
current cassette record being read. BLIM will have a value 


ranging from i to 128, depending upon the record control byte as 
explained in Section 5. 


Dii BPTR#* CO03B,1] -- Cassette-record data index 


BPTR contains an index into the data portion of the cassette 
record being read or written. The value will range from 0 to the 
then current value of BLIM. When BPTR equals BLIM then the buffer 
(CASBUF) is full if writing or empty if reading. 


Internal Working Variables 


Di2 FEOF# €OCOSF,1] -- Cassette end-of-file flag 


FEOF is used by the Cassette Handler to flag the detection of an 
end of file condition (control byte = $FE). FEOF equal to zero 
indicates that an EOF has not yet been detected, and a nonzero 
value indicates that an EOF has been detected. The flag is reset 
at every OPEN. 


DiS FTYPE# COOSE.1] -- Interrecord gap type 


FTYPE is a copy of ICAX2Z from the OPEN command and indicates the 
type of interrecord gap selectedi a positive value indicates 
normal record gaps, and a negative value indicates continuous 
mode gaps. 


Di4 WMODE+ (0289,1] -- Cassette read/write mode flag 

WMODE is used by the Cassette Handler to indicate whether the 
current operation is a read or write operationi a value of zero 
indicates read, and a value of $80 indicates write. 

DiS FREG@#* £0040,1] -- Beep count 

FREQ is used to retain and count the number of beeps requested of 


the BEEP routine by the Cassette Handler during the OPEN command 
process. 
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E. KEYBOARD 


See Section 5S for a general description of the Keyboard Handler. 


Key Reading and Debouncing 


The console key code register is read in response to an IRQ 
interrupt that is generated whenever a key stroke is detected by 
the hardware. The key code is compared with the prior key code 
accepted (CH1): if the codes are not identical, then the new code 
is accepted and stored in the key code FIFO (CH) and in the prior 
key code variable (CH1). If the codes are identical, then the new 
code is accepted only if a suitable key debounce delay has 
transpired since the prior value was accepted. 


If the key code read and accepted is the code for (CCTRLI] 1, then 
the display start/stop flag (SSFLAG) is complemented and the 
value is not stored in the key code FIFO (CH}. 


In addition to the reading of the key data, SRTIMR is set to $30 
for all interrupts received (see E88), and ATRACT is set to O 
whenever a new code is accepted (see B10}. 


The Keyboard Handler obtains all key data from CH: whenever a 
code is extracted from that i-byte FIFO, the Handler stores a 
value of FF to the FIFO to indicate that the code has been read. 
See Section S for further discussion of the Keyboard Handler ’s 
processing of the key codes. 


El CHi# (CO2F2,1] -- Prior keyboard character code. 

CHi contains the key code value of the key most recently read and 
accepted. 

E2 KEYDEL# CO2Fi.,1] -- Debounce delay timer. 

KEYDEL is set to a value of 3 whenever a key code is accepted, 
and is decremented every 60th of a second by the stage 2 VBLANK 
process (until it reaches zero). 

ES CH CO2FC,1] -- Keyboard character code FIFO. 

CH is a i-byte FIFO that contains either the value of the most 
recently read and accepted key code or the value $FF (which 
indicates that the FIFO is empty). The FIFO is normally read by 
the Keyboard Handler, but can be read by a user program. 

Key data can also be stored into CH by the Autorepeat logic as 


explained in the discussion relating to E®. 
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Special Functions 


Start/Stop 


Display Handler and Screen Editor output to the text or graphics 
mode screen can be stopped and started (without losing any of the 
output data} through the use of the CCTRLI] 1 key combination. 
Each key depression toggles a flag that is monitored by the above 
mentioned Handlers. When the flag is nonzero, the handlers wait 
for it to go to zero before continuing any output. 


E4 SSFLAG CO2FF,1] -- Start/stop flag 


The flag is normally zero, indicating that screen output is not 
to be stopped. The flag is complemented by every occurrence of 
the CCTRLJI 1 key combination by the keyboard IRG@ service routine. 


The flag is set to zero upon power-up, CSYSTEM. RESET] or CBREAKI 
key processing. 


[BREAK] Key 


ES BRAKKEY £0011,1] -- CBREAK] key flag 


BRKKEY is used to indicate that the CBREAK] key has been pressed. 
The value is normally nonzero and is set to zero whenever the 
CBREAK] key is pressed. The code that detects and processes the 
CBREAK] condition (flag = 0) should set the flag nonzero again. 


BRAKEY is monitored by the following OS routines: Keyboard 
Handler, Display Handler, Screen Editor, Cassette Handler, xx? 
The detection of a CBREAK] condition during an I/O operation 
will cause the operation to be aborted and a status of $80 to be 
returned to the user. 


The flag is set to nonzero upon Power-up, CSYSTEM. RESET] or upon 
aborting a pending I/0 operation. 


CSHIFTI/CCONTROL] Lock 


The keyboard control has three different modes for code 
generation that apply to the alphabetic keys A through Z: 
1} normal, 2) caps lock, and 3) control lock. 
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In normal mode, ali unmodified alphabetic character keys generate 
the lowercase letter ATASCII code ($61-7A}. 


In caps lock mode, all unmodified alphabetic character keys 
generate the uppercase letter ATASCII code ($41-SA}. 


In control lock mode, all unmodified alphabetic character keys 
generate the control letter ATASCII code ($01-1A). 


In all three modes. any alphabetic character key that is modified 
(by being pressed in conjunction with the CSHIFT] or {(CCTRLIJ key) 
will generate the desired modified code. 


E& SHFLOK CO2BE,1] -- Shift/control lock control flag 
SHFLOK normally has one of three values: 


$OO = normal mode (no locks in effect}. 
$40 = caps lock. 
$80 = control lock. 


SHFLOK is set to $40 upon Power-up and CSYSTEM. RESET] and is 
modified thereafter by the OS only when the €CAPS.LOWER] key is 
pressed (either by itself or in conjunction with the CSHIFTI or 
CCTRLI key?. 


E7 HOLDCH# (CO007C,11] -- Character holding variable 


HOLDCH is used to retain the current character value prior to the 
CSHIFTI/CCONTROL] logic process. 


Autorepeat 


The Autorepeat feature responds to the continuous depression of a 
keyboard key by replicating the key code 10 times per second, 
after an initial 1/2 second delay. The timer variable SRTIMR is 
used to control both the initial delay and the repeat rate. 


Whenever SRTIMR is equal to zero and a key is being held down, 
the value of the key code is stored in the key code FIFO (CH). 
This logic is part of the stage 2 VBLANK process. 


ES SRTIMR# (O022B,1] -- Autorepeat timer 


SRTIMR is controlled by two independent processes: 1) the 
keyboard IRQ service routine, which establishes the initial delay 
value and 2) the stage 2 VBLANK routine that establishes the 
repeat rate, decrements the timer and implements the auto repeat 
logic. 
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Inverse Video Control 


The Keyboard Handler allows the direct generation of more than 
half of the 256 ATASCII codes: but codes $80-9A and codes $A0- FC 
can be generated only with the “inverse video mode" active. The 
ATARI key acts as an on/off toggle for this mode, and all 
characters (except for screen editing control characters) will be 
subyect to inversion when the mode is active. 


E9 INVFLG €O02B6,.1] —-- Inverse video flag 

INVFLG is normally zero, indicating that normal video ATASCII 

codes (bit 7 = ©) are to be generated from keystrokes; whenever INVFLG 
is nonzero, inverse video ATASCII codes (bit 7 = 1) will be generated. 
The special control codes are exempt from this bit manipulation. 
INVFLG is set to zero by power-up and system reset. 

The Keyboard Handler inverts bit 7 of INVFLG whenever the ATARI key 

is pressed; the lower order bits are not altered and are assumed to be 
zero. 

The Keyboard Handler’s “exclusive or’s" (XOR‘’s} the ATASCII key data 


with the value in INVFLG at all times; the normal values of $00 and 
$80 thus lead to control of the inverse video bit (bit 7>?. 


Console Keys: CSELECT]., CSTART], and COPTION) 
The console keys are sensed directly from the hardware 


register CONSOL (CDOIF]i see the ATARI Home Computer 
Hardware Manual for details. 


F. PRINTER 


See Section S for a general description of the Printer Handler. 


Printer-Buffer 


Fi PRNBUF# (£03C0, 40] -- Printer-record buffer 


PRNBUF is the buffer used by the Printer Handler for packing printer 
data to be sent to the device controller. The buffer is 40 bytes long 
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and contains nothing but printer data. 


F2 PBUFSZ# COO1E,1] -- Printer-record size 


PBUFSZ contains the size of the Printer-record for the current mode 
selectedi the modes and respective sizes (in decimal bytes) are shown 


below: 
Normal 40 
Double width 20 (not currently supported by the device) 
Sideways 29 
Status request 4 
F3 PBPNT# COO1D,11] —--— Printer-buffer index 


PBPNT contains the current index to the Printer-buffer. PBPNT ranges 
in value from zero to the value of PBUFSZ. 


Internal Working Variables 


F4 PTEMP# COO1IF,11] -- Printer Handler temporary data save 


PTEMP is used by the Printer Handler to temporarily save the value of 
a character to be output to the printer. 


FS PTIMOT# COO1iC,1] -- Printer timeout value 

PTIMOT contains the timeout value for SIO calling sequence variable 
DTIMLO (see Section 9}; PTIMOT is set to 30 (which represents a 32 
second timeout) at intialization time, and is updated after each 


printer status request operation to contain the value returned in the 
third byte of the status frame (see Section 93}. 


G. CENTRAL 1/70 ROUTINE (CIO> 


See Section 5 for a description of the Central I/0 Utility. 


User Call Parameters 
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CIO call parameters are passed primarily through an I/0 Control 
Block (IOCB); although additional device status information can be 
returned in DVSTAT, and Handler information is obtained from the 
device table (HATABS}. 


I/O Control Block 


IOCB is the name applied collectively to the 14 bytes associated 
with each of the 8 provided control structures; see Section 5. 


Gi I0CB £0340,16] -- 1/0 Control Block 


The label IOCB is the location of the first byte of the first IOCB in 
the data base. For VIDs G2 through G10, the addresses given are for 
IOCB #0 only. the addresses for all of the IOCB’s are shown below: 


0340-034F IOCB #0 
0350-O35F IOCB #1 
0360-O036F IOCB #2 
0370-037F IOCB #3 
0380-O038F IOCB #4 
0390-O039F IOCB #5 
O3SA0-O3AF IOCB #6 
O3BO-O3SBF IOCB #7 


G2 ICHID (£0340.,11] -- Handler ID 


See Section 5S. Initialized to $FF at power-up and system reset. 


G3 ICBNO £0341,11] -- Device number 


See Section 5. 


G4 ICCOM [0342.11] -- Command byte 


See Section 5. 


GS ICSTA €0343,1] -- Status 


See Section 5. 


G6 ICBAL,. ICBAH (0344,2] -- Buffer address 


See Section 5. 
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G7 ICPTL, ICPTH CO0346,2] -- PUT BYTE vector 


See Section 5S. Initialized to point to CIO’s “IOCB not OPEN" routine 


at power-up and system reset. 


GS ICBLL, ICBLH (0348,2] -- Buffer length / byte count 


See Section 5. 


G9 ICAX1, ICAX2 C0344, 2] -- Auxiliary information 


See Section 5. 
GiO ICSPR ([034C,4] -- Spare bytes for Handler use 


There is no fixed assignment of these four bytes: the Handler 
associated with an IOCB can or may not use these bytes. 


Device Status 


Gii BVSTAT [CO2EA. 4] -- Device status 


See Section 5 for a discussion of the GET STATUS command. 


Device Table 


Gi2 HATABS COS1A, 38] -- Device table 


See Section 9 for a description of the device table. 


CiO/Handler Interface Parameters 


Communication between CIO and a Handler is accomplished using the 
6502 machine registers, and a data structure called the Zero-page 
IOCB (ZIOCB>). The ZIOCB is essentially a copy of the particular 
IOCB being used for the current operation. 
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Zero-Page IOCB 


Gi3 ZIOCB (IOCBAS) (0020,16] -- Zero-page IOCB 

The Zero-page IOCB is an exact copy (except as noted in the 
discussions that follow) of the IOCB specified by the 6502 X 
register upon entry to CIO; CIO copies the outer level IOCB to 
the Zero-~page IOCB, performs the indicated function, moves the 
(possibly altered) Zero-page IOCB back to the outer level IOCB, 
and then returns to the caller. 

Although both the outer level IOCB and the Zero-page IOCB are 
defined to be 14 bytes in size, only the first 12 bytes are moved 
by CIO. 

Gi4 ICHIDZ (0020,13 -- Handler index number 


See Section S. Set to $FF on CLOSE. 


GiS ICDNOZ (CO02i,1] -- Device drive number 


See Section 5. 


Gi6 ICCOMZ (C0022.1] -- Command byte 


See Section 5. 


Gi7 ICSTAZ (€0023,1] -- Status byte 


See Section 5. 


Gi8 ICBALZ, ICBALH [0024,2] -- Buffer address 

See Section 5S. This pointer variable is modified by CIO in the 
course of processing some commandsi however, the original value 
is restored before returning to the caller. 

Gi? ICPTLZ. ICPTHZ 

See Section 5S. Set to point to CIO’s “IOCB not OPEN" routine on 
CLOSE. 

G20 ICBLLZ, ICBLHZ (0028.2] -- Buffer length / byte count 


See Section 5S. This double-byte variable. which starts out 
representing the buffer length, is modified by CIO in the course 
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of processing some commands: then, before returning to the 
caller, the transaction byte count is stored therein. 


G2i ICAXKiZ, ICAX2Z ([O002A,2] -- Auxiliary information 


See Section 5S. 


G22 ICSPRZ CICIDNO, CIOCHR? CO002C, 4] -- CIO working variables 


ICSPRZ and ICSPRZ+1 are used by CIO in obtaining the appropriate 
Handler entry point from the handler’s vector table (see Section 9). 


ICSPRZ+2 is also labeled ICIBNO and retains the value of the 6502 X 
register from CIO entry. The X register is loaded from ICIDNO as CIO 
returns to the caller. 


ICSPRZ+3 is also labeled CIOCHR and retains the value of the 6502 A 
register from CIO entry, except for data reading type commands, in 
which case the most recent data byte read is stored in CIOCHR. The 
6502 A register is loaded from CIOCHR as CIO returns to the caller. 


Internal Working Variables 


G23 ICCOMT# [0017.1] -- Command table index 


ICCOMT is used as an index to CIO’s internal command table, which maps 
command byte values to Handler entry offsets (see Section 9 for more 
information). ICCOMT contains the value from ICCOMZ except when ICCOMZ 
is greater than $0E, in which case ICCOMT is set to $0E. 


G24 ICIDNO#x COO2E.1}] -- CIO call X register save/restore 
See Gee. 
G25 CIOCHR# COO2F,1] -- CIO call A register save/restore 
See Ged. 


H. SERIAL I/0 ROUTINE (SIO) 


See Section 9 for discussions relating to SIO. 
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User Call Parameters 


SIO call parameters are passed primarily through a Device Control 
Block: although an additional “noisy bus“ option exists that is 
selectable through a separate variable. 


Device Control Block 


Hi DCB (C030C.12] -- Bevice Control Block 


DCB is the name applied collectively to the 12 bytes at locations 
O30C-O3S0OB. These bytes provide the parameter passing mechanism for SIO 
and are described individually below. 


H2 DDEVIC £0300.1] -- Device bus ID 


See Section ?. 


H3 DUNIT (€0301.,11] -- Device unit number 


See Section 9. 


H4 DCOMND (€0302.,1] -- Device command 


See Section 3. 


HS DSTATS £0303,11] -- Device status 


See Section 39. 


H& DBUFLO, DBUFHI (C0304,2] -- Handler buffer address 


See Section 9. 


H7 DTIMLO £0306.,11] -- Device timeout 


See Section 3. 


HS DBYTLO, DBYTHI CO308,.2] -- Buffer length / byte count 


See Section 3. 


OPERATING SYSTEM CO016555 -- Appendix L 
238 


H9 DAUXi, DAUX2 CO3O0A, 2] -- Auxiliary information 


See Section 9. 


Bus Sound Control 


H1iO SOUNDR [0041.1] -- Quiet/noisy I/0 flag 


SOUNDR is a flag used to indicate to SIO whether noise is to be 
generated on the television audio circuit when Serial I/O bus 
activity is in progress. SOUNDR equal to zero indicates that 
sound is to be inhibited, and nonzero indicates that sound is to 
be enabled. SIO sets SOUNDR to 3 at power-up and system reset. 


Serial Bus Control 

Retry Logic 

SIO will attempt one complete command retry if the first attempt 
is not error free, where a complete command try consists of up to 


14 attempts to send (and acknowledge) a command frame, followed 


by a single attempt to receive COMPLETE and possibly a data 
frame. 


Hii CRETRY# (CO0036.1] -- Command frame retry counter 


CRETRY controls the inner loop of the retry logic, that associated 


with sending and receiving an acknowledgement of the command frame. 


CRETRY is set to 13 by SIO at the beginning of every command 
initiation, thus allowing for an initial attempt and up to 13 
additional retries. 


Hi2 DRETRY# (C0037,1] -- Device retry counter 


DRETRY controls the outer loop of the retry logic. that 
associated with initiating a command retry after a failure 
subsequent to the command frame acknowledgement. DRETRY is set to 
i by SIO at entry, thus allowing for an initial attempt and 

1 additional retry. 
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Checksum 


The Serial 1/70 bus protocol specifies that all command and data & 
frames must contain a checksum validation byte: this byte is the 


arithmetic sum (with end-around carry) of all of the other bytes 
in the frame. 


Hi3S CHKSUM# (0031.13 -- Checksum value 


CHASUM contains the frame checksum as computed by SIO for all frame 
transfers. 


H1i4 CHKSNT# COOC3B,13 -- Checksum sent flag 


CHKSNT indicates to the serial bus transmit interrupt service 
routine whether the frame checksum byte has been sent yet. CHKSNT 
equal to zero indicates that the checksum byte has not yet been 
sent; after the checksum is sent, CHASNT is then set nonzero. 


H1iS NOCKSM# CO0O3C,1] -~- No checksum follows data flag 


NOCKSM is a flag used to communicate between the SIO top level 

code and the Serial bus receive interrupt service routine that 

the next input will not be followed by a checksum byte. A value 

of zero specifies that a checksum byte will follow, nonzero specifies } 
that a checksum byte will not follow. 


Data Buffering 
General Buffer Control 


Hi6 BUFRLO# [0032.1] and BUFRHI# (CO0O33.1] -- Next byte address 


BUFRLO and BUFRHI comprise a pointer to the next buffer location 
to be read from or written to. For a data frame transfer, the 
pointer is initially set to the value contained in the SIO call 
parameters DBUFLO and DBUFHI., and is then incremented by the 
interrupt service routines as a part of normal bus data transfer. 
For a command frame transfer, the pointer is set to point to the 
SiO0-maintained command frame output buffer. 


Hi7 BFENLO# (0034,1] and BFENHI# (C0035,11] -- Buffer end address 


BFENLO/BFENHI form a pointer to the byte following the last frame 
data byte (not including the checksum) to be sent or received. ® 
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BFENLO/BFENHI is the arithmetic sum of BUFRLO/BUFRHI plus the 
frame size plus -1. 


Command Frame Output Buffer 


See Section 9 for the command frame format and description. 


H18 CDEVIC# CO23A.1}] -- Command frame device ID 

CDEVIC is set to the value obtained by adding SIO call parameter 
DDEVIC to DUNIT and subtracting 1. 

H1i9 CCOMND*# (CO23B.1] -- Command frame command. 

CCOMND is set to the value obtained from SIO call parameter 
DCOMND. 

H20 CAUX1I# CO023C.1] and CAUX2# (023D.,1] -- Auxiliary information 


CAUX1 and CAUX2 are set to the values obtained from SIO call 
parameters DAUX1 and DAUX2., respectively. 


Receive/Transmit Data Buffering 


H2i1 BUFRFL# (0038.1] -- Buffer full flag 


BUFRFL is a flag used by the serial bus receive interrupt service 
routine to indicate when the main portion of a bus frame has been 
received -- all but the checksum byte. BUFRFL equal to zero 
indicates that the main portion has not been completely received, 
a nonzero value indicates that the main portion has been 
received. 


H22 RECVDN# (C0039,1] -- Receive frame done flag 

RECVDN is a flag used by SIO to communicate between the Serial 
bus receive interrupt service routine and the main SIO code. The 
flag is initially set to zero by SIO. and later set nonzero by 
the interrupt service routine after the last byte of a bus frame 
has been received. 


H23 TEMP# CO23E,.1] -- SIO i-byte 1/0 data 
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TEMP is used to receive i-byte responses from serial bus 
controllers, such as ACK, NAK, COMPLETE or ERROR. 


H24 XMTDON+ [0034.11] -- Transmit frame done flag 


XMTDON is a flag used by SIO to communicate between the Serial 
bus transmit interrupt service routine and the main SIO code. The 
flag is initially set to zero by SIO, and later set nonzero by 
the interrupt service routine after the last byte of a bus frame 
has been transmitted. 


SIO Timeout 


SIO uses System Timer 1 to provide the timeout capability for 
various operations initiated internally. See Section 6 for a 
discussion of the capabilities of the System Timers. TIMFLG is 
the flag used to communicate between SIO and the timer initiated 
code pointed to by CDTMA1. 


H25 TIMFLG# €0317,1] -- SIO operation timeout flag 


TIMFLG is used to indicate a timeout situation for a bus 
operation . The flag is initially set to 1, and if it attains a 
value of zero (after the timeout period) before the current 
operation is complete, the operation will be aborted. See also 
D2. 


H26 CDTMVi* (C0218.2] -- System Timer 1 value 


This 2-byte count takes on various values depending upon the 
operation being timed. See also P4. 


H27 CDITMAi+ £C0226,2] -- System Timer 1 address 


This vector always points to the JTIMER routine. whose only 
function is to set TIMFLG to zero. This vector is initialized by 
SIO before every use, so that System Timer 1 can be used by any 
process that does not use SIO within a timing function. See also 
PS. 
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Internal Working Variables 


H28 STACKP# £0318.,1] -- Stack pointer save/restore 


STACKP contains the value of the 6502 SP register at entry to 
SIO; €his is retained to facilitate a direct error exit from an 
SIO subroutine. 


H29 TSTAT# €0319,1] -- Temporary status 


TSTAT is used to return the operation status from the WAIT 
routine and will contain one of the SIO status byte values as 
shown in Appendix B. 


H30 ERRFLG# (CO23F,.1] -- I/0 error flag 
ERRFLG is used for communication between the WAIT routine and the 


outer level SIO code. ERRFLG is normally zero, but is set to $FF 
when a device responds with an invalid response byte. 


H31 STATUS# (£0030,1] -- SIO operation status 
STATUS is a zero-page variable that is used within SIO to contain 


the operation status that will be stored to the calling sequence 
parameter variable DSTATS when SIO returns to the caller. 


H32 SSKCTL# CO232.1] -- SKCTL copy 


SSKCTL is utilized by SIO to keep track of the content of the 
SKACTL CD2OF] register, which is a write-only register. 


J. ATARI CONTROLLERS 
The ATARI controllers are read as part of the Stage 2 VBLANK 


process. The encoded data is partially decoded and processed as 
shown in the subsections that follow. 


Joysticks 


Up to four joystick controllers can be attached to the computer 
console, each with a 9-position joystick plus a trigger button. 
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Jl STICKO —- STICKS (£0278,4] -- Joystick position sense 


The 4 joystick position sense variables contain a bit-encoded 
position sense as shown below: 


7&5 4321 0 
+—4+-—4-4-4~—4—-4-4-4 
iO O GO CIRILIDivVit 
ee ee ee ee eee ee 


+ 
+ 


where: indicates joystick RIGHT sensor true. 
indicates joystick LEFT sensor true. 
indicates joystick DOWN sensor true. 


indicates joystick UP sensor true. 


oOo00 


R 
ies 
D 
U 


Nine unique combinations are possible, indicating the possible 
Joystick positions shown below: 


CENTER $0F 
UP $0E 
UP /RIGHT $06 
RIGHT $07 
DOWN/RIGHT $05 
DOWN $OD 
DOWN/LEFT %09 
Lert $OB 


UP/LEFT $O0A 


J2 STRIGO —- STRIGS £[0284,4] -- Joystick trigger sense 
The four joystick trigger sense variables each contain a single bit 


indicating the position of the joystick trigger as shown below: 


76S 49321 06 
Dede dee tees eke eee ee 
(00000 0 OtT! 
5 ea decisis sete ieee dee eieiaeied 


where: T = 0 indicates trigger pressed. 


Paddles 

Up to eight paddle controllers can be connected to the computer, 
each with a potentiometer and a trigger sense. 

J3 PADDLO - PADDL7 [0270,8] -- Paddle position sense 


There is a single-byte variable associated with each paddle 
position sensei the values range from 228 for full 
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counterclockwise rotation to 1 for full clockwise rotation. 


The paddle values are often converted by the user, as shown 
below, to give a result of O for full counterclockwise rotation 
and 227 for full clockwise rotation: 


VALUE := 228 - PADDLX;: 
J4 PTRIGO - PTRIG7 £027C,8] -- Paddle trigger sense 


The 8-paddle trigger sense variables each contain a single bit 
indicating the position of the paddle trigger as shown below: 


7&5 43210 
ee ee ee ee ee eS 
(9 00000 OTT! 
Ste tee ee ee le ee ee ee 


where: T = 0 indicates trigger pressed. 


Light Pen 


The OS reads the position of a single light pen and stores the 
horizontal and vertical position codes in two variables; these codes 
are not the same as the actual screen coordinates. The pen position 
codes for different portions of the screen are shown below: 


Left edge -- &7. 
Codes increase in increments of one to a value of 227, then go to O 
and continue to increase monotonically (one count per color clock). 
Right edge -- 7. 


Upper edge -- 16. 
Codes increase in increments of one (one count per two raster 
lines}. Lower edge -- i111. 


The light pen hardware will read and latch the pen position 60 times 
per second, independent of the pen button position, which is 
separately sensed. 


In order for the light pen to operate it must be positioned over a 
portion of the screen which has sufficient luminance to activate the 
photosensor in the pen; a blank (dark) screen will generally not 
provide enough luminance to utilize the light pen. 


J5 LPENH £0234,1] -- Light pen horizontal position code 
LPENH contains the horizontal position code for the light pen: the 
algorithm below (written in Pascal) shows the conversion from position 


code to screen coordinate (screen mode 7}: 


IF LPENH < 33 £ check for rollover point } 
THEN { adjust values to right of rollover } 
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XPOS := LPENH + 227 
ELSE { no adyustment to left of rollover point } 
XPOS := LPENH;: 
XPOS := XPOS —- 67; { adyust for left edge offset } 
IF XPOS < O THEN XPOS := Q; 
IF XPOS > 159 THEN XPOS := 159; 


J¥6&é (LPENV £0235. 11] -- Light pen vertical position code 


LPENYV contains the vertical position code for the light pen; the 
algorithm below (written in Pascal? shows the conversion from position 
code to screen coordinate (screen mode 7}: 


YPOS := LPENV —- 16; { adyust for upper edge offset } 
IF YPOS < ©O THEN YPOS := QO; 
IF YPOS > 95 THEN YPOS := 95; 


J7 STICKO — STICKS (£0278. 4] -- Light pen button sense 


The light pen button sense is encoded in one of STICKO - STICKS 
(depending upon the actual controller port used) as shown 
below: 


7 0 
Seals ieee deals dete dee aie a 
H iO1O1oirTi 
S eiaeaici dead aie aaa 


where: T = © indicates the light pen button is pressed. 


Driving Controllers 


The driving controller has no position stops and thus allows unlimited 
rotation in either direction: the output of the controller is a 2-bit 
Gray code which can be used to determine the direction of rotation. 
The controller is sensed using the same internal hardware as the 
joystick, thus the same data base variables are used for both. 
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JG STICKO - STICKS (0278,41] -- Driving controller sense 


The 4 driving controller sense variables contain an encoded 
Totation (position) sense value, as shown below: 


7&5 4321 0 
en en on on on a coo 
(0 000i Livali 
+ — HH H+ 


where a clockwise rotation of the controller produces the following 
continuous sequence of four values (shown in hexadecimal}: 


OF, OB. OC, OE. OF, OD,....... 


and a counterclockwise rotation of the controller produces the 
following continuous sequence of four values: 


OF, OF, OC, OD, OF, OE,....... 


J9 STRIGO —- STRIGS (£0284,41] -- Driving trigger sense 


The four driving trigger sense variables each contain a single bit 
indicating the position of the driving trigger as shown below: 


76543210 
ee ee ee ee a ae er 
(O00 0000 OT 
+ — + — + — $4 — 4 + 4 + 


where: T = 0 indicates trigger pressed. 


K. DISK FILE MANAGER 

See Section 5 for information relating to the Disk File Manager. 

Ki FMSZPCG# [006043,7] -- FMS reserved space 

FMSZPG is the reserved space in the database for the variables shown 


below; the names associated with K2 through KS are not in the system 
equate file. 


K2 ZBUFPs# £0043,2] -- Buffer pointer 
K3 ZDRVA# (€0045,2] -- Drive pointer 
K4 ZSBA* (0047,2] -- Sector buffer pointer 
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KS ERRNO# (£0049,11] -- Error number 


cs 


Li 


DISK UTILITY POINTER 


DSKAUTL# COO1LA, 2] -- Page-zero pointer variable 


M. FLOATING POINT PACKAGE 


See Section 8 for a description of the Floating Point Package. 


Mi 


M2 


M3 


M4 


MS 


M& 


M7 


M8 


M? 


M10 


Mil 


Mi2 
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FRO COOD4,&] -- FP register 0 

FRE# COODA, 6] -- FP register (internal) 
FRi COOEG, 6] -- FP register i 

FR2% COCES, 6] -- FP register 2 (internal) 
FRX# COGOEC,13] -- Spare (unused? 


EEXP# COOED., 1] -- Exponent 


NSIGN#® COOEE,1] -- Sign of 


ESIGN# {CCOEF,1] -- Sign of 


FCHRFLG# COOFO, 1] -- First 


DIGRT# COOFi,1] -- Digits 


CIX COOF2. 1] -- Character 


value (internal? 


mantissa (internal } 


exponent (Cinternal} 


character flag (internal) 


to right of decimal point 


index 


INBUFF COOFS, 2] -- Input text buffer pointer 
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M13 ZTEMP1# COOFS.,2] -- Temporary storage 


M14 ZTEMP4# COOF7.,2] -- Temporary storage 


M15 ZTEMPS* COOF9, 2] -- Temporary storage 


Mi6é FLPTR COOFC,2] -- Pointer to FP number 


M17 FPTR2* COOFE. 2] --— FP package use 


Mi8 LBPRi# COS7E,.11] -- LBUFF preamble 


M19 CBPR2* COS7F.1] -- LBUFF preamble 


M20 LBUFF COS80, 946] -- Text buffer 


M2il PLYARG# COSEO, 46] -- FP register (internal? 


M22 FPSCR/FSCR* COSEG, 6] -- FP register (internal?) 


M23 FPSCRiI/SCRi# COSEC,6] -~ FP register (internal? 


M24 DEGFLG/RADFLG COOFB,13 -- Degrees/radians flag 


DEGFLG = 0 indicates radians, 6& indicates degrees. 


N. Power-Up and SYSTEM RESET 


See Section 7 for details of the power-up and system reset 
operations. 


RAM Sizing 


During power-up and system reset the first non-RAM address above 1000 
hex is located and its address retained using a nondestructive 

test. The first byte of every 4K memory “block" is tested to see if 
it is alterable; if so, the original value is restored and the next 
block is tested, and if not. that address is considered to be the 

end of RAM. 
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Ni RAMLO#/TRAMSZ# [0004,3] -- RAM data/test pointer (temporary) 


RAMLO+1 contains the LSB of the address to be tested (always = QO? 
and TRAMSZ (same as RAMLO+2) contains the MSB of the address to be 
tested. RAMLO+0O contains the complemented value of the data 
originally contained in the memory location being tested. 


later in the initialization process these variables are used for 
totally unrelated functions: but first the value in TRAMSZ is moved 
to the variables RAMSIZ and MEMTOP+1. 


N2 TSTDAT# £0007,1]3 -- Test data byte save 


TSTDAT contains the original value of the memory location being 
tested. 


Diskette/Cassette-Boot 


As a part of the Power-up sequence, software can be booted from an 
attached disk drive or cassette player as explained in Section 10. 


N3 DOSINI [GC00C,2] -- Diskette-boot initialization vector. 


DOSINI contains the disk booted software initialization address 
from the beginning of the boot file (see Section 10) whenever a 
diskette-boot is successfully completed. 


N4 CKEY# £004A.1] -- Cassette-boot request flag 


CKEY is an internal flag used to indicate that the console CSTARTI 
key was pressed during Power-up, thus indicating that a 
cassette-boot is desired. CKEY equals zero when no cassette-boot is 
requested, and is nonzero when a cassette-boot is requested. The 
flag is cleared to zero after a cassette-boot. 


NS CASSBT# £004B,11] -- Cassette-booting flag 

CASSBT is used during the cassette-boot process to indicate to 

shared code that the cassette is being booted and not the diskette. 
CASSBT equal to zero indicates a diskette-boot, and nonzero indicates 
a cassette-boot. 


N& CASINI (£0002,2] -- Cassette-boot initialization vector 


CASINI contains the cassette-booted software initialization address 
from the beginning of the boot file (see Section 10) whenever a 
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cassette-boot is successfully completed. 


N7 BOOT?# COOO9,1] -- Successful diskette/cassette-boot flag. 


BOOT? indicates to the initialization processor which, if any, of 
the boot operations went to successful completion. The flag values 
are set by the OS and the format for the variable is shown below: 


745432106 
+—+—-4+-—4-4+-4-—4-4-—4+ 
H iCiBt 
5 suai alata sea seats dante sions see a 


where: C = 1 indicates that the cassette-boot was completed. 
D= 1 indicates that the diskette-boot was completed. 
NG DFLAGS# (£0240,1] -- Diskette flags 


DFLAGS contains the value of the first byte of the boot file, after a 
diskette-boot. See Section 10. 


NO DBSECT# £0241,1] -- Diskette-boot sector count 


DBSECT is initially set to the value of the second byte of the boot 
file. during a diskette-boot, and is then used to control the number 
of additional diskette sectors read, if any. 


NiO BOOTAD# ([0242,2] -- Diskette-boot memory address 


BOOTAD is initially set to the value of the third and fourth 
bytes of the boot file, during a diskette-boot, and is not 
modified thereafter. 


Environment Control 


If, at the end of a power-up or system reset, control is not 

given to one of the cartridges (as explained in Sections 7 and 10), 
then program control passes to the address contained in the data 
base variable DOSVEC. 


Nii COLDST# (0244,1] -- Coldstart complete flag 
COLDST is used by the initialization routine to detect the case of 
a system reset occurring before the completion of the power-up 


process. COLDST is set to SFF at the beginning of the power-up 
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sequence and is set to 0 at the completion: if a system reset 
occurs while the value is nonzero, the power-up sequence will be 
reinitiated (rather than initiating a system reset sequence). 


Ni2 DOSVEC ([000A, 2] -- Noncartridge control vector 


At the beginning of power-up the OS sets DOSVEC to point to the 
“blackboard” routine: DOSVEC can then be altered as a consequence 
of a diskette-boot or cassette-boot (as explained in Section 10) to 
establish a new control program. Control will be passed through 
DOSVEC on all power-up and system reset conditions in which a 
cartridge does not take control first. 


System Reset 


Ni3 WARMST [0008.1] -- Warmstart flag 


WARMST equals $FF during a system reset (warmstart) 
initialization and equals O during a power-up initialization 
(coldstart>}. 


P. INTERRUPTS 


See Section & for a discussion of interrupt processing. 


Pi CRITIC (€0042,1] -- Critical code section flag 


CRITIC is used to signal to the VBLANK interrupt processor that a 
critical code section is executing without IRG interrupts being 
inhibitedi the VBLANK interrupt processor will’ stop interrupt 
processing after stage i and before stage 2 just as if the 6502 
processor I bit were set, when CRITIC is set. 


CRITIC equal to zero indicates that the currently executing code 
section is noncritical, while any nonzero value indicates that the 
currently executing code section is critical. 


P2 POKMSK £0010,1] -- POKEY interrupt mask 


POKMSK is a software maintained interrupt mask that is used in 
conyunction with the enabling and disabling of the various POKEY 
interrupts. This mask is required because the POKEY interrupt 
enable register IRGEN CD20E] is a write-only register, and at any 
point in time the system can have several users independently 
enabling and disabling POKEY interrupts. POKMSK is updated by the 
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users fo always contain the current content of IRGEN. 


System Timers 


The System Timers are discussed in detail in Section 6. 


Realtime Clock 

The realtime clock (Cor frame counter, as it is sometimes called) 
is incremented as part of the stage i VBLANK process as explained 
in Section 6. 

P3 RTCLOK C€OO0i2, 3] -- Realtime frame counter 

RTCLOK+O is the most significant byte, RTCLOK+1 the next most 


Significant byte, and RTCLOK+2 the least significant byte. See the 
discussions at DG and preceding B10 for OS use of RTCLOK. 


System Timer i 

System Timer 1 is maintained as part of the stage i VBLANK process, 
and thus has the highest priority of any of the user timers. 

P4 CBITMV1 (0218.2] -- System Timer 1 value 

CDTMVi contains zero when the timer is inactive, otherwise it 


contains the number of VBLANKs remaining until timeout. Also see 
H26. 


PS CDBITMAiI €0226,2] -- System Timer i jump address 


CDTMAi contains the address to which to JSR should the timer 
timeout. See also H27 and Section &. 
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System Timer 2 

System Timer 2 is maintained as part of the stage 2 VBLANK process, 
and has the second highest priority of the user timers. The OS does 
not have any direct use for System Timer 2. 

P& CDTMV2 £021A.2] -- System Timer 2 value 

CDIMV2 contains zero when the timer is inactive, otherwise it 
contains the number of VBLANKs remaining until timeout. 

P7 CDTMA2 (0228.2] —-- System Timer 2 jump address 


CDTMA2 contains the address to which to JSR should the timer 
timeout. See Section 6&6. 


System Timers 3. 4 and 5 


System Timers 3. 4 and 5S are maintained as part of the stage 2 
VBLANK process, and have the lowest priority of the user timers. 
The OS does not have any direct use for these timers. 


P8 CDTMV3 [£021C.2], CDITMV4 CO2iE,.2] and CDTMVS (C0220, 2] 

These variables contain zero when the corresponding timers are 
inactive, otherwise they contain the number of VBLANKs remaining 
until timeout. 

P9 CDITMFS3S (CO22A.1]., CDIMF4 (O22C,1] and CDIMFS (CO22E, 2] 

Each of these i-byte variables will be set to zero should its 
corresponding timer timeout. The OS never modifies these bytes 
except to set them to zero upon timeout (and initialization). 

RAM Interrupt Vectors 

There are RAM vectors for many of the interrupt conditions within 


the system. See Section & for a discussion of the placing of values 
to these vectors. 
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NMI Interrupt Vectors 


P10 VDSLST [0200.2] -- Display-list interrupt vector 


This vector is not used by the OS. See Section 64. 


Pii VVBLKI CO222,2] -- Immediate VBLANK vector 


This vector is initialized to point to the OS stage 1 VBLANK 


Pi2 VVBLKD £0224,2] -- Deferred VBLANK vector 


This vector is initialized to point to the OS VBLANK exit routine. 
See Section &. 


IRG@ Interrupt Vectors 


Pi3 VIMIRG@ €0216,2] -- General IRQ vector 

This vector is initialized to point to the OS IRG@ interrupt 
processor. See Section &. 

P14 VPRCED €0202,2] -- Serial 1/0 bus proceed signal 

The serial bus line that produces this interrupt is not used in the 
current system. See Section 6. ) 
P15 VINTER £(0204,2] -- Serial I/0 bus interrupt signal 

The serial bus line that produces this interrupt is not used in the 
current system. See Section 64. 

Pi6é VCBREAKI] £0206,2] -- BRK instruction vector 

This vector is initialized to point to a PLA. RTI sequence as the 
OS proper does not utilize the BRK instruction. See Section 6. 

P17 VKEYBD (C0208, 2] -- Keyboard interrupt vector 

This vector is initialized to point to the Keyboard Handler ’s 


interrupt service routine. See Section & and the discussion 
preceding E1. 
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Pi8 VSERIN £02GA, 2] -- Serial I/0 bus receive data ready 


This vector is initialized to point to the SIO utility’s interrupt @ 
service routine. See Section 6. 


Pi9 VSEROR €020C,2] -- Serial I/0 bus transmit ready 

This vector is initialized to point to the SIO utility’s interrupt 
service routine. See Section &. 

P20 VSEROC CO20E,2] -- Serial I/0 bus transmit complete 

This vector is initialized to point to the SIO utility’s interrupt 
service routine. See Section &. 

P21 VTIMRi (0210,2], VTIMR2 CO212,2] and VTIMR4 (£0214,2] -- POKEY 


timer vectors 


The POKEY timer interrupts are not used by the OS See Section 6&4. 


Hardware Register Updates 


As part of the stage 2 VBLANK process, certain hardware registers _ 
are updated from OS data base variables as explained in Section 6. 


P22 SDMCTL# CO22F,1] -- DMA control 


SDMCTL is set to a value of $02 at the beginning of a Display 
Handler OPEN command, and then later set to a value of $22. The 
value of SDMCTL is stored to DMACTL CD400] as part of the stage 2 
VBLANK process. 


P23 SDLSTL# (0230,1] and SDLSTH# (CO231,1] -- Display list address 


The Display Handler formats a new display list with every OPEN 
command and puts the display list address in SDLSTL and SDLSTH. The 
value of these bytes are stored to DLISTL (CD402] and DLISTH [D403] 
as part of the stage 2 VBLANK process. 


0360-O036F IOCB #2 
0370-O037F IOCB #3 
O380-O38F IOCB #4 
0390-O39F IOCB #5 
O3AG-O3AF IOCB #6 
O3B0-O3BF IOCB #7 
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NOTE: There is a potential timing problem associated with the 
updating of the hardware registers from the data base variables. 
Since the stage 2 VBLANK process is performed with interrupts 
enabled, it is possible for an IRG@ interrupt to occur before the 
updating of DLISTH and DLISTL. If the processing of that 
interrupt (plus other nested interrupts) exceeds the 
vertical-blank delay (1 msec), then the display list pointer 
register will not have been updated when display list processing 
commences for the new frame, and a screen glitch will result. 


P24 GPRIOR# CO26F,1] -- Priority control 


The Display Handler alters bits & and 7 of GPRIOR as part of 
establishing the GTIA mode. The value of GPRIOR is stored to 
PRIOR CDO1BJ] as part of the stage 2 VBLANK process. 


P25 CHACT# CO2F3.,1] -- Character control 


The Display Handler sets CHACT to $02 on every OPEN command. The 
value of CHACT is stored to CHACTL (€D401] as part of the stage 2 
VBLANK process. 


P26 CHBAS (O2F4,1] -- Character address base 


The Display Handler sets CHBAS to $EO on every OPEN command. The 
value of CHBAS is stored to CHBASE [CD409] as part of the stage 2 
VBLANK process. This variable controls the character subset for 
screen modes 1 and 2; a value of $EO provides the capital letters 
and number set whereas a value of $E2 provides the lowercase 
letters and special graphics set. See BSS for more information. 


P27 PCOLRx (CO2CO,4] and COLORx (02C4,5] -- Color registers 


See B?7 and B8. 


Internal Working Variables 


P28 INTEMP# (CO22D,1] -- Temporary storage 


INTEMP is used by the SETVBL (SETVBYV) routine. 
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R. USER AREAS 
The areas shown below are available to the user in a non-nested & 
environment. See Section 4 for further information. 


Ri COO80. i128] 


R2 C0460, 640] 
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ALPHABETICAL LIST OF DATA BASE VARIABLES 


NAME 


ADDCOR 
ADRESS 
APPMHI 
ATACHR 
ATRACT 


BFENHI 


BUFRLO 
BUFSTR 


CASBUF 
CASFLG 
CASINI 
CASSBT 
CAUX1 

CAUX2 

CBAUDH 
CBAUDL 
CCOMND 
CDEVIC 
CDTMAi 
CDTMA2 
CDTMF3 
CDTMF 4 
CDTMFS 
CDTMVi 
CDTMV2 
CBTMV3 


VID 
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ADDRESS SIZE 


OSOE, 1 
0064, 2 
OOOE, 2 
O2FB, 1 
OO4D, 1 


0035, 1 
0034, 1 
COGE, 1 
O28A, 1 
0009, 1 
0242.2 
O2BF, 1 


OOS3D, 1 
0011, 1 
0015, 2 
OOGB, 1 
0038, 1 
0033, 1 
0032, 1 
006C, 2 


OSFD, 131 


OSOF, 1 
0002, 2 
OO4B, 1 
O23C, 1 
O023D, i 
O2EF, 1 
O2EE, 1 
O23B, 1 
O23A, 1 
0226, 2 
0228, 2 
O22A, 1 
O22C, 1 
O22E, 1 
0226, 2 
O21A,.2 
O21C,2 


CDTMV4 
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O21E, 
0220, 
O2FC, 
OOSB, 
O2F2, 
O2F3, 
O2FA, 
O2F 4, 
OO3B, 
0031, 
OCO02F, 
OOF 2, 
OO4A, 
0072, 
0055, 
0244, 
OO7A, 
02C4, 
O2C5, 
02CG, 
02C7, 
02C8, 
OO4F, 
OO7E, 
0036, 
0042, 
O2FO, 
0288, 


OSOA, 1 
OSOB, 2 
0241, 1 
0304, 1 
0305, 1 
0308, 1 
0309, 1 
0300, 1 
0302, 1 
0300, 1 
OOFB, 1 
0077, 2 
0076, 1 
0240, 1 
OOF 1, 1 
0057, 1 
O2A0, 1 
OO0C, 2 
OOOA, 2 
0037, 1 
OO4E, I 
0246, 1 
OO1A, 2 
O2FE, 1 
004C, 1 


2 
2 


beh pe et pet Pe ee ee et ee et ee fl PQ et ee et et et et 


2 


DSTATS 
DTIMLO 
DUNIT 

DUNUSE 
DVSTAT 


EEXP 
ENDPT 
ERRFLG 
(ERRNO 
ESCFLG 
ESIGN 


FCHRFL 
FEOF 
FILDAT 
FILFLG 
FLPTR 
FMSZPG 
FPSCR 
FPSCRI1 
FPTR2 
FRO 
FR1 
FR2 
FRE 
FREQ 
FRMADR 
FRX 
FSCR 
FSCR1 
FTYPE 


GPRIOR 


HATABS 
HOLD1 
HOLD2 
HOLDS 
HOLD4 
HOLDCH 


ICAX1 
ICAX1iZ 
ICAX2 
ICAX22Z 
ICBAH 
ICBAHZ 
ICBAL 
ICBALZ 
ICBLH 
ICBLHZ 
ICBLL 
ICBLL2Z 
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0303, 1 
0304, 1 
0301, 1 
0307, 1 
O2EA, 4 


OOED, 1 
0074.2 
O23F, 1 
0049, Ii 
O2A2, 1 
OOEF, 1 


COFO, 1 
OOSF, 1 
O2FD, 1 
02B7, 1 
OOFC,2 
0043, 7 
OSEG, & 
OSEC, 6 
OOFE, 2 
OOD4, & 
OOEO, 6 
OOCESG, & 
OODA, 6 
0040, 1 
0068, 2 
OOEC, 1 
OSEG, 6 
OSEC,4& 
COSE, 1 


O26F, 1 


O31A, 38 
0051, 1 
C29F, 1 
O29D, 1 
O2BC, 1 
CO7C, 1 


0344, 1 
OO2A, 1 
O34B, 1 
O02B, 1 
0345, 1 
0025, 1 
0344, 1 
0024, 1 
0349, 1 
0029, 1 
0348, 1 
0028, 1 


ICCOM 
ICCOMT 
ICCOMZ 
ICDNO 
ICDNOZ 
ICHID 
ICHIDZ 
IC IDNO 
ICP TH 
ICPTHZ 
ICPTL 
ICPTLZ 
ICSPR 
ICSPRZ 
ICSTA 
ICSTAZ 
INBUFF 
INSDAT 
INTEMP 
INVFLG 
IOCB 
IOCBAS 


KEYDEL 


LBFEND 
LBPR1i 
LBPR2 
LBUFF 
LINBUF 
LMARGN 
LOGCOL. 
LOGMAP 


MEMLO 
MEMTOP 
MLTTMP 


NEWCOL 
NEWROW 
NOCKSM 
NSIGN 


OLDADR 
OLDCHR 
OLDCOL 
OLDROW 
OPNTMP 


PADDLO 
PADDL1 
PADDL2 
PADDL3 
PADDL4 
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G4 0342, 1 
G23 0017, 1 
G16 0022, 1 
G3 0341, 1 
G15 0021, 1 
G2 0340, Ii 
G14 0020, 1 
G24, Ge 2002E, i 
G7 0347,1 
G19 0027, 1 
G7 0346, 1 
G19 00264, 1 
G10 O34C, 4 
G22 002C, 4 
GS 0343, 1 
Gi7 0023, 1 
Mi2 OOF 3, 2 
B45 007D, 1 
P28 O22D, 1 
E9 O2B4, 1 
G1 0340, 16 
G13 0020, 14 
E2 O2F 1,1 
M20 0580, 94 
M18 OS7E, 1 
M19 OS7F, 1 
M20 0580, 96 
B31 0247, 40 
BS OOS2, 1 
BiS 0063, 1 
B1i4 O2B2, 4 
Al O2E7, 2 
A2 O2ES, 2 
B40 0066, 2 
Bi? 0061,2 
Bi? 0040, 1 
H1S 0O3C, 1 
M7 OOEE, 1 
B38 OOSE, 2 
B37 OOSD, 1 
B3 OOSB, 2 
B3 OOSA, 1 
B40 0064, 2 
JS 0270, 1 
JS 0271,1 
J3 0272, 1 
JS 0273, 1 
JS 0274, 1 
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PADDLS 
PADDL& 
PADDL7 
PBPNT 

PBUFSZ 
PCOLRO 
PCOLR1 
PCOLR2 
PCOLR3 
PLYARG 
POKMSK 
PRNBUF 
PTEMP 

PTIMOT 
PTRIGO 
PTRIGL 
PTRIG2 
PTRIGS 
PTRIG4 
PTRIGS 
PTRIGS6 
PTRIG7 


RADFLG 
RAMLO 

RAMSIZ 
RAMTOP 
RECVDN 
RMARGN 
ROWAC 

ROWCRS 
ROWINC 
RTCLOK 


SAVADR 
SAVIO 
SAVMSC 
SCRFLG 
SDLSTH 
SDLSTL 
SDMCTL 
SHF AMT 
SHFLOK 
SOUNDR 
SRTIMR 
SSFLAG 
SSKCTL 
STACKP 
STATUS 
STICKO 
STICKi 
STICK2 
STICKS 
STRIGO 


Ji, J7, JB 
Ji, J7, JB 
J2, J7, JP 
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0275, 1 
0276, 1 
0277, 1 
CO1D, 1 
OO1E, 1 
02CO, 1 
O2C1,1 
02C2, i 
O02C3, 1 
OSEO, & 
0010, 1 
O3CO, 40 
OO1F, 1 
OO1C, i 
027C, 1 
027D, 1 
O27E, 1 
O27F, 1 
0280, 1 
0281, 1 
0282, 1 
0283, 1 


OOFB, i 
0004, 3 
O2E4, 1 
OOGA, 1 
0039, 1 
0053, 1 
0070, 2 
0054. 1 
0079, 1 
0012,3 


0068, 2 
0316, 1 
0058, 2 
O2BB, 1 
0231, 1 
0230, i 
O22F, 1 
OO4GF, 1 
O2BE, 1 
0041,1 
O22B, 1 
O2FF, 1 
0232, I 
0318, 1 
0030, 1 
0278, 1 
0279, 1 
027A, 1 
O27B, 1 
0284, 1 


STRIG1 
STRIG2 
STRIGS 
SUBTMP 
SWPFLG 


TABMAP 
TEMP 
TEMP 1 
TEMPS 
TIMER1 
TIMER2 
TIMFLG 
TINDEX 
TMPCHR 
TMPCOL 
TMPLBT 
TMPROW 
TOADR 
TRAMSZ 
TSTAT 
TSTDAT 
TXTCOL 
TXTMSC 
TXTOLD 
TXTROW 


USAREA 


VBREAK 
VDSLST 
VIMIRG 
VINTER 
VAEYBD 
VPRCED 
VSERIN 
VSEROC 
VSEROR 
VTIMR1 
VTIMR2 
VTIMR4 
VVBLKD 
VVBLKI 


WARMST 
WMODE 


XMTDON 


(ZBUFF 
(ZDRVA 
ZIOCB 
(ZSBA 
ZTEMP 1 
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Ja, J7, SP 
Ja, J7, SD 
J2, J7, JP 


B48 
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0285, 1 
0286, 1 
0284, 4 
O29E, 1 
0078, 1 


O2A3, 15 
O23E, 1 
O31i2.2 
0315, 1 
O30C, 2 
0310, 2 
0317, 1 
0293. 1 
0050, 1 
02B9, 2 
O2A1, 1 
O2B8, 1 
00664, 2 
0004, 3 
0319, 1 
0007, 1 
0291.2 
0294, 2 
0296, & 
0290, 1 


0080, 128 


0206, 2 
0200, 2 
0216, 2 
0204, 2 
0208, 2 
0202, 2 
O20A, 2 
O20E, 2 
020C,2 
0210, 2 
0212.2 
0214,2 
0224, 2 
O222. 2 


0008, I 
0289, 1 


OO3A, 1 


0043, 2 
0045, 2 
0020, 16 
0047,2 
OOFS, 2 


ZTEMPS M15 OOF?, 2 
@ ZTEMP4 M14 OOF 7; 2 
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MEMORY ADDRESS ORDERED LIST OF DATABASE VARIABLES 


a enneemeeennaneenneenenemnemeneen cement eeereeneenneeneieeeremnemnmanennmeememnenen emnneninennnneninrnenne Renn ne 


ADDRESS 


0000-0001 
0002-0003 
0004-0006 
0007 
0008 
0009 
OO0A-—-OCOB 
O00C-OCOD 
OCOOE—-OOOF 
0010 
0011 
0012-0014 
0015-0016 
0017 
001A-O01B 
OO1C 
001D 
OO1E 
OO1F 
0020 
0021 
0022 
0023 
0024-0025 
0026-0027 
0028-0029 
002A-002B 
002C-O02F 
0030 
0031 
0032-0033 
0034-0035 
0036 
0037 
0038 
0039 
OO3A 
003B 
0O3C 
O03D 
COSE 
OO3F 
0040 
0041 
0042 
0043-0049 
004A 
004B 
OO04C 
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VID NAME 

$7 LNZBS 

N6 CASINI 

Ni RAMLO. TRAMSZ 
N2 TSTDAT 

N13 WARMST 

N7 BOOT’? 

Ni2 DOSVEC 

NS DOSINI 

AS APPMHI 

P2 POKMSK 

ES BRKKEY 

P3 RTCLOK 

C1 BUFADR 

G23 ICCOMT 

Li DSKUTL 

FS PTIMOT 

F3 PBPNT 

Fe PBUFSZ 

F4 PTEMP 

G1i3,¢14 ICHIDZ 

G15 ICDNOZ 

G16 ICCOMZ 

G17 ICOBAS 

Gis ICBALZ, ICBAHZ 
G19 ICPTLZ, ICPTHZ 
G20 ICBLLZ, ICBLHZ 
G21 ICAX1Z, ICAX2Z 
G22, 624,625 ICSPRZ 

H3i STATUS 

His CHKSUM 

H16 BUFRLO, BUFFRHI 
H1i7 BFENLO, BFENHI 
Hil CRETRY 

Hi2 DRETRY 

H2 i BUFRFL 

H22 RECVDN 

H24 XMTDON 

H1i4 CHASNT 

H1iS NOCKSM 

Dili BPTR 

Di3 FTYPE 

Di2 FEOF 

Bis FREQ 

Hid SOUNDR 

Pi CRITIC 


Al, Ke, KS, K4, KS ZBUFF, ZBUFP, ZDRVA, ZSBA 
N4 CKEY 

NS CASSBT 

B34 DSTAT 
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004D 
OO4E 
OO4F 
0050 
0051 
0052 
0053 
0054-0056 
0057 
0058-0059 
OOSA-OCSC 
O0O5SD 
OOSE-OCSF 
0060-0062 
0063 
0064-0065 
0066-0067 
0068-0069 
O06A 
OO4B 
O006C-O006D 
O06E 
OO6F 
0070-0073 
0074-0075 
0076-0078 
0079-0074 
007B 
007C 
007D 
OO7E-OCO7F 


0O080-OOFF 
0100-O1FF 


0200-0201 
0202-6203 
0204-0205 
0206-0207 
0208-0209 
O20A-020B 
020C—-020D 
O20E-O20F 
0210-0215 
0216-0217 
0218-0219 
021A-021B 
021C-O0221 
0222-0223 
0224-0225 
0226-0227 
0228-0229 
022A 


SEE FLOATING 
6502 STACK 


P10 
Pi4 
P1iS 
P16 
Pi7 
P18 
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ATRACT 

DRKAMSK 

COLRSH 

TMPCHR 

HOLDi 

LMARGN 

RMARGN 
ROWCRS, COLCRS 
DINDEX 

SAVMSC 

OL DROW, OLDCOL 
OLDCHR 

OLDADR 
NEWROW, NEWCOL 
LOGCOL 

ADRESS 


MLTTMP, OPNTMP, TOADR 


SAVADR /FRMADR 

RAMTOP 

BUFCNT 
BUFSTR 
BITMSK 

SHF AMT 

ROWAC, COLAC 

ENDPT 

DELTAR, DELTAC 

ROWINC, COLINC 

SWPFLG 

HOLDCH 

INSDAT 

COUNTR 


POINT VARIABLE LIST AT END. 


VDSLST 
VPRCED 
VINTER 
VBREAK 
VKEYBD 
VSERIN 
VSEROR 
VSEROC 


VITMR1, VITMR2, VITMR4 


VIMIRG 
CDTMV1 
CDTMV2 


CDTMV3, CDTMV4, CDTMVS 


VVBLKI 
VVBLKD 
CDTMA1 
CDTMA2 
CDTMF3 
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022B 
O22C 
022D 
O22E 
O22F 
0230-0231 
0232 
023A 
0238 
023C-023D 
O23E 
023F 
0240 
0241 
0242-0243 
0244 
0246 
0247-O026E 
O26F 
0270-0277 
0278-027B 
027C-0283 
0284-0287 
0289 
O2BA 
O028B-028F 
0290-0292 
0293 
0294-0295 
0296-0298 
029D 
O29E 
029F 
O2A0 
O2A1 
02A2 
O2A3-O02B1 
C2B2-02B5 
O2B6 
O02B7 
O2B8-O02BA 
O2BB 
O2BC 
O2BE 
O2BF 
02C0-02C3 
02C 4-02C8 
O2E4 
O2E5-O02E6 
O02E7-O02E8 
O2EA-O2ED 
O2EE-O2EF 
O2F 0 
O2F 1 
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J1, J7, J8 


J4 


Je, J7, JD 


SRTIMR 
CDTMF 4 
INTEMP 
CDTMFS5 
SDMCTL 


SDLSTL, 


SSKCTL 
CDEVIC 
CCOMND 


SDLSTH 


CAUX1, CAUX2 


TEMP 

ERRFLG 
DFLAGS 
DBSECT 
BOOTAD 
COLDST 
DSKTIM 


LINBUF 


GPRIOR 
PADDLO 
STICKO 
PTRIGO 
STRIGO 
WMODE 
BLIM 
unused 


PADDL?7 
STICKS 
PTRIG7 
STRIGS 


TXTROW, TXTCOL 


TINDE X 
TXTMSC 
TXTOLD 
HOLDS 

SUBTMP 
HOLD2 

DMASK 

TMPLBT 
ESCFLG 
TABMAP 
LOGMAP 
INVFLG 
FILFLG 


TMPROW, TMPCOL 


SCRFLG 
HOLD4 

SHFLOK 
BOTSCR 
PCOLRO 
PCOLRO 
RAMSIZ 
MEMTOP 
MEMLO 

DVSTAT 


-- PCOLRS 
-- PCOLR4 


CHBAUDL, CHBAUBH 


CRSINH 
KEYDEL 
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O2F2 
O2F3 
O2F4 
O2FA 
O2FB 
O2FC 
O2FD 
O2FE 
O2FF 


0300 
O301 
0302 
0303 
0304-0305 
0306 
0308-0309 
O30A-O30B 
OS3SO0C-O30B 
OS0E 
OSOF 
0310-0311 
0312-0313 
0315 
0316 
0317 
0318 
0319 
O031A-O33F 
0340 
0341 
0342 
0343 
0344-0345 


0346-0347 
0348-0349 
034A-034B 
034C-O34F 
0350-O035F 
0360-O036F 
0370-037F 
O380-O38F 
0390-O039F 
O3A0-OS3AF 
O3B0-O3BF 
O3CO0-03E7 


OSFD-047F 


0480-O06FF 


DSPFLG 
SSFLAG 


DCB/DDEVIC 
DUNIT 
DCOMND 
DSTATS 
DBUFLO,. DBUFHI 
DTIMLO 
DBYTLO,. DBYTHI 
DAUX1, DAUX2 
TIMER1 
ADDCOR 
CASFLG 
TIMER2 
TEMP 1 

TEMPS 

SAVIO 
TIMFLG 
STACKP 
TSTAT 
HATABS 
IOCB., ICHID 
ICDNO 

ICCOM 

ICSTA 
ICBAL, ICBAH 


ICPTL. ICPTH 
ICBLL, ICBLH 
ICAX1, ICAX2 
ICSPR 
(IOCB #1} 
(IOCB #2} 
(IOCB #3) 
(IOCB #4} 
(IOCB #5) 
(IOCB #6) 
(IOCB #7} 
PRNBUF 


CASBUF 


User Area 
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FLOATING POINT PACKAGE VARIABLES 


O00OD4-00D9 
OODA-OODF 
OOEO-O00ES 
OOE46—-O0EB 
OOEC 
OOED 
OOEE 
OOEF 
OOF O 
OOF 1 
OOF 2 
OOF 3-OCOF 4 
OOF 5-OOF6 
OOF 7-O0OF8 
OOF 9-OOFA 
OOFB 
OOF C-OOFD 
OOF E-OOFF 


OS7E 
OS7F 
0580-O05FF 
OSEO-OSES 
OSE6-O5EB 
OSEC-OSF 1 
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M1 FRO 

M2 FRE 

M3 FR1 

M4 FR2 

MS FRX 

M6 EEXP 

M7 NSIGN 

MS ESIGN 

M9 FCHRFLG 
M10 DIGRT 

Mii CIXx 

Mi2 INBUFF 

M13 ZTEMP 1 

M14 ZTEMP4 

M15 ZTEMPS 

M24 RADFLG/DEGFLG 
M16 FLPTR 

M17 FPTR2 

M1i8 LBPRi 

M19 LBPR2 

M20 LBFEND, LBUFF 
M2i PLYARG 

M22 FPSCR/FSCR 
M23 FPSCRi/SCR1 
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INDEX 


The subysect index contains three forms of references: 


such as 
such as ‘App B’ 


Section number, 
Appendix, 


Variable ID from Appendix L, 


ATARI standards 
ATASCII 
attract mode 


bit mapped graphics 
blackboard mode 

BNF 

boot 

BREAK 


cartridge 

cassette baud rate determine 
cassette-boot 

cassette device 

Cassette Handler (C) 

CIO (Central I/0 Utility> 
CiO/user interface 
CiIO/Handler interface 
CLOSE I/0 command 
coldstart (see ‘Power-—up ’) 
color control 

control characters 
critical section 

cursor 


database 

DCB (Device Control Block) 
DELETE I/70 command 
development system 
device/filename specification 
Device Handler 

device table 

disk-boot 

disk device 

Disk File Manager (D} 

Disk Handler (resident> 
display device (screen) 
Display Handler (5S) 
display list 

DOS (Disk Utilities) 

DRAW 1/0 command 

driving controller 


‘3. 


f 


such as ‘’B7’%. 


12 
B54-55, 
Bi0-i2, 


ae 
&, 


App D-G 


B28-B29, 
3, Nia, 
1 

<7 
ES, 


2) 
71 


App H 
i2 


4, 
6, 


N3-10, 
12 


3: 7, 10 


a 4, 
Di-D7 
3, N3-10, Zu 
D1-D15, a re 
2 

Gi-25, 35. 9 

Gi-11, 5S. App A. 
Gi2-22, 9? 

2 


7, 10 


10 


App B 


B7-8, he & 
B2e6-27, 3, 
Pi, & 
Bi-4, 5 


App DBD 


4 
Hi-9, 
2 

13 

2 

2 
2, Gi2, 5S, 
3 N3-10, 
2 

Ki-S, 5 
Ci-2, ~) 
BS4-55, 
Bi-S5, 5S 
4, P10 
Li, 12 
Bi7-25, 5 
J8-9 


>» F 


7. 9 


2 7s 10 


2, App E. App H 
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GS, HS, Hi1-12, 9, App B-C 
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EOF (end-of-file>) > 


File Management System 2 © 
FILL I/O command Bi7-25, § 

floating point package 2, 4 Mi-24, 8. App J 

FORMAT I/0 command 2 

free memory 4, Ai-3, Ri-2. 4 7 

game controllers a: JI-9, & i11 

GET CHARACTER I/0 command S..$ 

GET RECORD 1/0 command a F 

GET STATUS 1/70 command Gil, 3 9 


Handler (see ‘device handler’ and individual device handlers) 


initialization, cartridge 7 
initialization, Handler 47t-9 
initialization. interrupt & 
initialization. system 4, 7, 10 
internal display code 9, BS4 
interrupts 2, Pi-28, 6 
interrupt mask P2, 6& 
inverse video (display? EY, 93 

I/O 2a, 4 3 
IOCB (I/0 Control Block) Gi-10. 5, 9 
I/O retry logic Hii-i2 
joystick Ji-2 
keyboard Autorepeat ES 

keyboard device 2 

Keyboard Handler (K)} Ei-9, 3S, App F 
keyboard key debouncing Ei=3 

light pen 11, App J 
LNBUG i3 

LOCK I/0 command 2 


logical text lines (screen) Bi4-15, §$ 


memory (see ‘RAM’, ‘ROM’ and ‘free memory‘? 


memory dynamics Ai-S, Ni-2, 4 3S, 7 
memory map 4 
NOTE I/0 command me 
OPEN I/0 command 2. 
paddle J3-4 
page 0 4, Mi-17, Ril. 
page i 4, 9 
peripheral devices 3 
POINT I/0 command 3 
Power-up 2, Ni-13, 4. 7% 12 
printer device o>, App G 
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Printer Handler (P? 
program development 

PUT CHARACTER I/0 command 
PUT RECORD I/0 command 


RAM 

record (1/03 

RENAME 1/70 command 
RESET 

ROM (0S} 

RS-232-C Handler (R) 


Screen Editor (E) 
screen margins 

screen modes 

scrolling (text) 
serial I/O bus 
CSHIFTI/CONTROL lock 
SIO (Serial bus I/0 Utility?) 
sound control (SIO? 
SPECIAL 1/0 commands 
split screen 

stack 

start/stop (display? 
stage i VBLANK process 
stage 2 VBLANK process 


tabs (Screen Editor) 
timeout (device) 
timers (system? 


UNLOCK I/0 command 
user workspace 


vectors, RAM 
vectors, ROM 
vertical blank interrupt 


warmstart (see ‘RESET’ } 
wild-card (disk filename) 


ZIOCB (Zero~-page IOCB) 
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2: Ni-13, &, 71 i2 


H1i-Se, 
H1iO, ii 
3» GF 
Bié, § 
4 

E4, 5. ile 

P3-35, 6 

P6-9, P2e2-27, & 


Pi3-2i, 35. 9. App C 


Bi3. § 
H25-27, 9 
P3-9, & 


2 
4, M18-23, R2 


PS, P7, P10-21, &, 9 
2, F, App J 

Pi 1-i2, & 

2 


Gi3-22, 7, 0020, 16 
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